Install HYTHE

Start with one agent, then connect a second. HYTHE 0.2.0 can run in Docker on your computer or on a dedicated server. Choose where to keep your shared memory, then point each client at that server.

The server host needs Git, Docker with Compose, and Node.js 20.9 or newer for initialization. Client-only computers need Node.js 20.9 or newer and an MCP-compatible application. The shell examples use a POSIX shell (Linux, macOS, or WSL on Windows); use absolute paths appropriate to the operating system running each client. No particular hostname, username, or installed shell shortcuts are required.

See the setup overview for the architecture and verification steps.

1. Get the server source on your chosen host

The npm package supplies the client bridge. Building the server requires the tagged source checkout.

git clone --depth 1 --branch v0.2.0 https://github.com/hythe-dev/hythe.git
cd hythe
node bin/engram-mcp.cjs init --write-env --agent-id agent-a

Run initialization inside the checkout: it writes .env there with mode 0600 and refuses to overwrite an existing file. Keep that file private. A second initialization without --write-env prints configuration without changing the credential.

2. Start and reach your server

Local Docker

docker compose -f docker/docker-compose.yml up -d
curl -fsS http://127.0.0.1:6174/ready

Wait for ready: true and degraded: false. First startup downloads an embedding model; inspect Compose logs if it is still starting. Ports bind to loopback by default. This starts an empty local store, separate from any existing installation.

Dedicated server

Run the checkout, initialization, and Docker Compose commands above on the server. Keep the default loopback port bindings. The container's persistent volume holds the database and model cache; your client computers do not need their own server containers.

A simple remote connection is an SSH tunnel. On each client computer, replace user@your-server with your SSH login:

ssh -N -o ExitOnForwardFailure=yes -L 127.0.0.1:16174:127.0.0.1:6174 user@your-server

Keep that SSH process running. In another terminal on the client, verify readiness:

curl -fsS http://127.0.0.1:16174/ready

For this tunnel, use MCP_HOST=127.0.0.1 and MCP_PORT=16174 in every client configuration below. Port 16174 is a local example chosen to avoid colliding with a local HYTHE server; use another free port if needed.

Alternatively, use a protected gateway on a private network and set MCP_HOST and MCP_PORT to its endpoint. The Compose default remains loopback-only: setting a client hostname does not make the server reachable remotely. Configure the gateway or tunnel first. The bridge uses HTTP, so remote traffic needs the protection of the SSH tunnel or private network; do not expose its plain HTTP port to the public internet.

On each client computer, retain a checkout of the same release for the bridge (the git clone command in step 1). Provision a protected credential file containing the deployment key for the chosen server, and point HYTHE_API_KEY_FILE to that local file. Do not initialize a fresh server key on each client: a new unrelated key will not authenticate to the existing server. For enforced identities, also provision that agent's distinct credential file using the authorization guide.

Keep backups on the server and a separate backup destination. Follow the backup and restore guide; do not synchronize the live database file between client computers.

3. Connect a client

0.2.0 command correction: the released wizard prints a bare npx @hythe/mcp command. The package has two executables, so use the explicit binary below. Do not copy that part of the generated configuration unchanged.

From a shell outside a checkout of @hythe/mcp, the bridge command is:

npx -y -p @hythe/mcp@0.2.0 hythe-mcp

For clients that can start from any working directory, use absolute paths to Node and the bridge in your retained release checkout. npm --prefix alone does not reliably avoid a matching unlinked checkout. The bridge also needs the exact identity, absolute credential-file path, host, and port. Regenerate paths after moving or upgrading Node or HYTHE.

Example Codex configuration for local Docker; replace the Node, bridge, and credential paths with your own. For the SSH tunnel, change MCP_PORT to 16174. Configure one HYTHE integration, avoiding duplicate standalone and plugin servers:

[mcp_servers.hythe]
command = "/absolute/path/to/node"
args = ["/absolute/path/to/hythe/bin/engram-mcp.cjs"]
env = { HYTHE_AGENT_ID = "agent-a", HYTHE_API_KEY_FILE = "/absolute/path/to/hythe/.env", HYTHE_AGENT_AUTH_MODE = "observe", MCP_HOST = "127.0.0.1", MCP_PORT = "6174" }

For Claude Code, use the same identity for both its MCP bridge and the process that runs plugin hooks:

claude plugin marketplace add hythe-dev/hythe
claude plugin install hythe
claude mcp add hythe --env HYTHE_AGENT_ID=agent-a --env HYTHE_API_KEY_FILE="$PWD/.env" --env HYTHE_AGENT_AUTH_MODE=observe --env MCP_HOST=127.0.0.1 --env MCP_PORT=6174 -- node "$PWD/bin/engram-mcp.cjs"
HYTHE_AGENT_ID=agent-a claude

The claude mcp add example runs from the client checkout so $PWD/.env names its protected credential file. For a dedicated server, provision that file with the existing deployment key first and change MCP_PORT to 16174 when using the tunnel above. The absolute bridge path stays valid when the client starts in another directory. The same environment and argument list can be used in a JSON MCP configuration. Install the appropriate session hooks for each client; a bridge connection alone does not establish compaction recovery. See client checks.

4. Verify the lane

Check initialization version 0.2.0 and tools/list (20 advertised tools on the reference server). The bridge attempts registration asynchronously; confirm the exact identity through get_agent_status. A durable role/identity entity is separate from that registration.

Ask the agent to checkpoint a small project, resume it, and read its own inbox. Give the second client a different identity, agent-b, and the same server address and protected key-file reference. Have A send B a handoff naming the project; B reads its inbox and resumes that scope. Confirm the recorded state and sender, not just a model's claim that it connected.

5. Use v3 deliberately

{"agentId":"agent-a","scope":{"project":"hello-fleet"},"budget":2000,"sections":["working","heads","currentFacts","openLoops"],"resultVersion":3}

A new scope's first checkpoint establishes its current pointer. Older scopes may need explicit reconciliation before the v3 facts view is authoritative. See what changed in 0.2.0.

Identity and enforcement

This bootstrap uses observe mode for compatibility. Stable labels bind local clients but do not prove server-enforced agent identity. Full enforcement needs a per-agent credential and the documented observe → mixed → required rollout. See the release security model.

Troubleshooting

• Server still starting: follow docker compose -f docker/docker-compose.yml logs -f engram on the server host; the first model download can take time.
• Connection refused: check readiness on the server, then check the tunnel or private gateway from the client.
• Authentication failed: verify the credential file belongs to the chosen server and is readable only by its intended user. Confirm the configured agent-auth mode matches the rollout.
• Unexpected or empty memory: check the server endpoint and project scope. A local test container and a dedicated server are independent installations.
• Wrong identity: keep the bridge, hooks, and trusted session identity consistent. Give simultaneous agents distinct IDs.

Source and verification

Based on release quickstart, with the explicit-executable correction above. Commands and generated files are checked independently of the upstream wording. See verification evidence for the scope and dates of exercised paths.