HASH

This is HASH's public monorepo which contains our public code, docs, and other key resources.

  What is HASH?

HASH supports turning raw information into knowledge and process graphs, helping create graph-backed world models that power process automation, optimization, decision making, and AI. In essence, HASH is a self-building, open-source database which grows, structures and checks itself. Integrating data in (near-)realtime, it provides a powerful set of interfaces so that information can be understood and used in any context. Intelligent, autonomous agents can be deployed to grow, check, and maintain the database, collating and structuring information from the public internet — as well as your own connected private sources — in a standardized semantic form. Users, including those who are non-technical, are able to visually browse and manage both entities (data) and types (schemas). HASH acts as a source of truth for critical data, no matter its source, and provides a platform for high-trust, safety-assured decision-making. Read our blog post →

Many of HASH's features are unique to a platform of its kind, including its support for bitemporality, which provides first-order support for recording and querying both when something happened and, separately, when it became known. This capability is central to our support for better process modeling.

  Getting started

Instructions for using HASH can be found in the HASH Developer Docs.

  Option 1. Use hash.ai — recommended (quick-start: <5 mins) 🚀

Create an account

Create an account to get started.

Sign in

Sign in to access your account.

Skip the queue

When you first create an account you may be placed on a waitlist. To jump the queue, once signed in, follow the instructions shown in your HASH dashboard. All submissions are reviewed by a member of the team.

  Option 2. Run HASH locally

Running HASH locally

These instructions set up HASH for working on the codebase — the app services run natively with hot-reload against containerised infrastructure. To run the whole stack from container images instead (no toolchain required on the host), follow the setup guide.

Prerequisites

Install these on the host first:

• Git (≥ 2.17)
• Docker (≥ 20.10), including:
  • Docker Compose (≥ 2.17) — orchestrates the stack
  • Docker Buildx (≥ 0.10) — builds the images
• mise — installs and pins Node, Rust, protoc and the other required tool versions

Give Docker at least 8 GB RAM (Preferences → Resources) and keep ~15 GB of disk free for build artefacts, images and volumes.

Check your versions:

git --version            # ≥ 2.17
docker --version         # ≥ 20.10
docker compose version   # ≥ 2.17
docker buildx version    # ≥ 0.10

Setup

1. Clone the repository and enter it:

   git clone https://github.com/hashintel/hash.git && cd hash

2. Install the pinned toolchains (mise trust is required once per clone), then activate mise in your shell:

   mise trust && mise install

3. Install JavaScript dependencies:

   yarn install

4. Create a .env.local in the repository root. Real keys are only needed for AI features — dummy values work otherwise:

   OPENAI_API_KEY=dummy
   ANTHROPIC_API_KEY=dummy
   HASH_TEMPORAL_WORKER_AI_AWS_ACCESS_KEY_ID=dummy
   HASH_TEMPORAL_WORKER_AI_AWS_SECRET_ACCESS_KEY=dummy

   .env.local is git-ignored and overrides .env and .env.development. Don't edit the other .env files unless you mean to change the defaults.

5. Start the containerised infrastructure:

   yarn compose up -d

   This runs the dev and observability profiles — Postgres, Redis, Kratos, Hydra, Temporal, Vault and MinIO, plus the Grafana stack (http://localhost:3001) and the Temporal UI (http://localhost:3100/namespaces/HASH). The graph layer is not included; you run it as part of the app below.

6. Start HASH. The simplest is to run everything natively (this compiles the graph from Rust, 10–20 min on a cold first build):

   yarn start

   For hot-reload on the api and frontend, run the graph and the app in separate terminals instead:

   yarn start:graph   # terminal 1 — compiles and runs the graph
   yarn dev           # terminal 2 — api + frontend with hot-reload

   The dev-mode API seeds three users (password password): alice@example.com, bob@example.com (regular) and admin@example.com (admin). Visit http://localhost:3000 once the API logs localhost:5001.

Skipping the Rust build

If you're not working on the graph itself, run it in Docker instead of compiling Rust locally — add the hgres profile and start only the api + frontend natively:

yarn compose --profile hgres up -d   # infrastructure + graph in Docker
yarn dev                             # api + frontend only

Running the browser plugin

If you need to run the browser plugin locally, see the README.md in the apps/plugin-browser directory.

Resetting the local database

If you need to reset the local database, to clear out test data or because it has become corrupted during development:

1. Run yarn compose down -v (this will take the Docker services down and drop the volumes)
2. Run yarn compose up -d to start everything again

Sending emails

Email-sending in HASH is handled by either Kratos (in the case of authentication-related emails) or through the HASH API Email Transport (for everything else).

To use AwsSesEmailTransporter, set export HASH_EMAIL_TRANSPORTER=aws in your terminal before running the app, along with SYSTEM_EMAIL_ADDRESS and SYSTEM_EMAIL_SENDER_NAME (which control what address and name the email appears to be from). Valid AWS credentials are required for this email transporter to work.

Transactional emails templates are located in the following locations:

• Kratos emails in ./infra/compose/kratos/templates/. This directory contains the following templates:
  • recovery_code - Email templates for the account recovery flow using a code for the UI.
    • When an email belongs to a registered HASH user, it will use the valid template, otherwise the invalid template is used.
  • verification_code - Email verification templates for the account registration flow using a code for the UI.
    • When an email belongs to a registered HASH user, it will use the valid template, otherwise the invalid template is used.
• HASH emails in apps/hash-api/src/email/index.ts

  Option 3. Deploying HASH to the cloud

Deploying HASH to the cloud

See the self-hosting guide for running HASH on infrastructure you operate. The full Docker Compose topology — graph, API, frontend, auth, workflows, storage and observability — lives in infra/compose/ and is the starting point for a self-hosted deployment.

  Examples

Discover ways to use HASH by browsing the use cases directory, or check out the Awesome HASH repository for more inspiration.

  Roadmap

Browse the HASH development roadmap for more information about currently in-flight and upcoming features.

  About this repository

  Repository structure

Repository structure

This repository's contents is divided across several primary sections:

• /apps contains the primary code powering our runnable applications
  • The HASH application itself is divided into various different services which can be found in this directory.
• /blocks contains our public Block Protocol blocks
• /infra houses deployment scripts, utilities and other infrastructure useful in running our apps
• /libs contains libraries including npm packages and Rust crates
• /tests contains end-to-end and integration tests that span across one or more apps, blocks or libs

  Environment variables

Environment variables

Here's a list of possible environment variables. Everything that's necessary already has a default value.

You do not need to set any environment variables to run the application.

General API server environment variables

• NODE_ENV: ("development" or "production") the runtime environment. Controls default logging levels and output formatting.
• PORT: the port number the API will listen on.

AWS configuration

If you want to use AWS for file uploads or emails, you will need to have it configured:

• AWS_REGION: The region, eg. us-east-1
• AWS_ACCESS_KEY_ID: Your AWS access key
• AWS_SECRET_ACCESS_KEY: Your AWS secret key
• AWS_S3_UPLOADS_BUCKET: The name of the bucket to use for file uploads (if you want to use S3 for file uploads), eg: my_uploads_bucket
• AWS_S3_UPLOADS_ACCESS_KEY_ID: (optional) the AWS access key ID to use for file uploads. Must be provided along with the secret access key if the API is not otherwise authorized to access the bucket (e.g. via an IAM role).
• AWS_S3_UPLOADS_SECRET_ACCESS_KEY: (optional) the AWS secret access key to use for file uploads.
• AWS_S3_UPLOADS_ENDPOINT: (optional) the endpoint to use for S3 operations. If not, the AWS S3 default for the given region is used. Useful if you are using a different S3-compatible storage provider.
• AWS_S3_UPLOADS_FORCE_PATH_STYLE: (optional) set true if your S3 setup requires path-style rather than virtual hosted-style S3 requests.

For some in-browser functionality (e.g. document previewing), you must configure a Access-Control-Allow-Origin header on your bucket to be something other than '*'.

File uploads

By default, files are uploaded locally, which is not recommended for production use. It is also possible to upload files on AWS S3.

• FILE_UPLOAD_PROVIDER: Which type of provider is used for file uploads. Possible values LOCAL_FILE_SYSTEM, or AWS_S3. If choosing S3, then you need to configure the AWS_S3_UPLOADS_ variables above.
• LOCAL_FILE_UPLOAD_PATH: Relative path to store uploaded files if using the local file system storage provider. Default is var/uploads (the var folder is the folder normally used for application data)

Email

During development, the dummy email transporter writes emails to a local folder.

• HASH_EMAIL_TRANSPORTER: dummy, aws, or smtp. If set to dummy, the local dummy email transporter will be used in development or test environments (it logs to the console).
• DUMMY_EMAIL_TRANSPORTER_FILE_PATH: Default is var/api/dummy-email-transporter/email-dumps.yml
• SYSTEM_EMAIL_SENDER_NAME: the display name for the email sender (required if transport is aws or smtp)
• SYSTEM_EMAIL_ADDRESS: the email address for the email sender (required if transport is aws or smtp)
• SMTP_SERVER_HOST: the host for a SMTP server (required if transporter is smtp)
• SMTP_SERVER_PORT: the port for a SMTP server (required if transporter is smtp)
• SMTP_SERVER_USERNAME: auth username for SMTP server (optional if API is automatically authenticated)
• SMTP_SERVER_PASSWORD: password for SMTP server (optional if API is automatically authenticated)

Postgres

• POSTGRES_PORT (default: 5432)

Various services also have their own configuration.

The Postgres superuser is configured through:

• POSTGRES_USER (default: postgres)
• POSTGRES_PASSWORD (default: postgres)

The Postgres information for Kratos is configured through:

• HASH_KRATOS_PG_USER (default: kratos)
• HASH_KRATOS_PG_PASSWORD (default: kratos)
• HASH_KRATOS_PG_DATABASE (default: kratos)

The Postgres information for Temporal is configured through:

• HASH_TEMPORAL_PG_USER (default: temporal)
• HASH_TEMPORAL_PG_PASSWORD (default: temporal)
• HASH_TEMPORAL_PG_DATABASE (default: temporal)
• HASH_TEMPORAL_VISIBILITY_PG_DATABASE (default: temporal_visibility)

The Postgres information for the graph query layer is configured through:

• HASH_GRAPH_PG_USER (default: graph)
• HASH_GRAPH_PG_PASSWORD (default: graph)
• HASH_GRAPH_PG_DATABASE (default: graph)

Redis

• HASH_REDIS_HOST (default: localhost)
• HASH_REDIS_PORT (default: 6379)

Snowplow telemetry

• HASH_TELEMETRY_ENABLED: whether Snowplow is used or not. true or false. (default: false)
• HASH_TELEMETRY_HTTPS: set to "1" to connect to the Snowplow over an HTTPS connection. true or false. (default: false)
• HASH_TELEMETRY_DESTINATION: the hostname of the Snowplow tracker endpoint to connect to. (required)
• HASH_TELEMETRY_APP_ID: ID used to differentiate application by. Can be any string. (default: hash-workspace-app)

Others

• FRONTEND_URL: URL of the frontend website for links (default: http://localhost:3000)
• NOTIFICATION_POLL_INTERVAL: the interval in milliseconds at which the frontend will poll for new notifications, or 0 for no polling. (default: 10_000)
• HASH_INTEGRATION_QUEUE_NAME The name of the Redis queue which updates to entities are published to
• API_ORIGIN: The origin that the API service can be reached on (default: http://localhost:5001)
• SESSION_SECRET: The secret used to sign sessions (default: secret)
• LOG_LEVEL: the level of runtime logs that should be omitted, either set to debug, info, warn, error (default: info)
• BLOCK_PROTOCOL_API_KEY: the api key for fetching blocks from the Þ Hub. Generate a key at https://blockprotocol.org/settings/api-keys.

  Contributing

Please see CONTRIBUTING if you're interested in getting involved in the design or development of HASH.

We're also hiring for a number of key roles. We generally don't accept applications for engineering roles like a normal company might, preferring to headhunt (using HASH as a tool to help us find the best people)... but contributing to our public monorepo, even in a small way, is one way of guaranteeing you end up on our radar as every PR is reviewed by a human, as well as AI.

We also provide repo-specific example configuration files you can use for popular IDEs, including VSCode or Zed.

  License

The vast majority of this repository is published as free, open-source software. Please see LICENSE for more information about the specific licenses under which the different parts are available.

  Security

Please see SECURITY for instructions around reporting issues, and details of which package versions we actively support.

  Contact

Find us on 𝕏 at @hashai, email hey@hash.ai, create a discussion, or open an issue for quick help and community support.

Project permalink: https://github.com/hashintel/hash