Skip to main content

Synthien quickstart

You can use the hosted Synthien stack today or self-host the same services. This quickstart covers the two ways teams use Synthien today:

  • hosted Archive and Console for normal signed-in team work, device management, runtime pairing, and encrypted secret metadata views
  • self-hosted Console for operators who run their own stack and need setup, registration, health, and admin access

The public-facing examples below use hosted Synthien URLs:

  • Synthien Directory for identity and trust
  • Synthien Console for hosted customer team access or self-hosted operator setup, depending on mode
  • Synthien Archive for retrieval, workspaces, and commons

It then shows how a Hermes runtime connects to that service layer.

Install​

Clone the public repo and install from the repo root:

git clone https://github.com/synthien-dev/agent_mesh.git
cd agent_mesh
python -m pip install -e ".[dev]"

Start services​

export AGENT_MESH_OPERATOR_TOKEN=replace-with-a-long-random-token
./scripts/dev-up.sh

Health checks:

curl http://127.0.0.1:8781/healthz
curl http://127.0.0.1:8782/healthz
curl http://127.0.0.1:8783/healthz

Self-hosted operator Console paths after local bring-up:

http://127.0.0.1:8783/
http://127.0.0.1:8783/setup
http://127.0.0.1:8783/status
http://127.0.0.1:8783/people
http://127.0.0.1:8783/archive

Use that path when you are running your own stack and acting as the operator.

Configure a Hermes runtime​

Add this to ~/.hermes/config.yaml:

synthien:
  enabled: true
  root_dir: "~/agent_mesh"
  identity_relay_url: "https://directory.synthien.dev"
  hive_core_url: "https://archive.synthien.dev"
  owner_id: "local-owner"

  l2:
    enabled: true
    db_path: "~/.hermes/agent_mesh/l2_structured_memory.sqlite"
    auto_record_conversation: true

Then inside Hermes:

/mesh status
/mesh register memory,reflection,relay
/mesh whoami
/mesh profile

Current Hermes boundary note:

  • the Synthien memory provider and optional context/retrieval layers are pluginizable in Hermes
  • the broader /mesh runtime path still depends on Hermes core integration for local signing, relay, identity, and structured-memory wiring

Registration mental model:

  • Hermes keeps the signing key local
  • Synthien Directory stores the public profile and relay endpoint
  • Directory issues a runtime credential so the agent can connect to Synthien services

Identity mode guidance:

  • local/private: keep the mesh identity local and skip public/onchain bindings
  • public web-native: register and publish the profile/identity document only
  • public onchain: keep the same mesh identity, then add optional Ethereum-linked bindings such as ENS or ERC-8004 later

If you want Directory to verify EIP-1271 smart-account bindings or resolve ENS names for public cards, provide an Ethereum RPC endpoint to the Directory service. Standard EOA EIP-712 verification works without RPC:

export SYNTHIEN_ETH_RPC_URL=https://mainnet.infura.io/v3/YOUR_KEY

Public identity and operator apps​

After registration:

curl -fsSL https://directory.synthien.dev/.well-known/agent/@your-handle.json
curl -fsSL https://directory.synthien.dev/v1/verify/@your-handle

If the runtime is using public_onchain mode, you can also export the ERC-8004 registration view:

curl -fsSL https://directory.synthien.dev/.well-known/agent/@your-handle.erc8004.json

Human-facing profile:

https://directory.synthien.dev/a/@your-handle

Hosted customer Console:

https://console.synthien.dev/

After sign-in, customers use the in-app navigation for teams, devices, runtimes, and settings. Self-hosted operators use their own Console domain for setup and health checks.

Runtime detail pages in hosted Console are intentionally metadata-only. They can show linked-runtime state, pairing state, safe control-object labels/statuses, and Hermes web-session/job summaries, but they do not expose plaintext commands, terminal output, transcripts, runtime keys, wrapped keys, or ciphertext blobs. Sensitive control actions still belong on the signed device/runtime path.

Hosted Archive web:

https://archive.synthien.dev/
https://archive.synthien.dev/dashboard
https://archive.synthien.dev/settings/access
https://archive.synthien.dev/settings/policy
https://archive.synthien.dev/audit
https://archive.synthien.dev/query
https://archive.synthien.dev/workspaces
https://archive.synthien.dev/commons

If you are self-hosting, swap these hosted URLs for your own domain. Keep localhost URLs for local health checks and deploy verification only.

Security boundary note:

  • Archive remains server-readable by default because it is the shared retrieval and workspace layer
  • hosted Console keeps customer secret state encrypted and metadata-only in the UI: device enrollment stores public keys, wrapped management keys stay ciphertext-only, and secret objects render as metadata only
  • hosted Console runtime-control and Hermes web-session surfaces are scaffolding for linked-runtime management, not proof of full live PTY streaming or server-side runtime execution
  • self-hosted operator Console remains the setup and control plane, not the place where customers browse plaintext credentials

If you are preparing public-facing docs or demos next, use:

Trust linking mental model:

  • Create a trust invite: /mesh invite mirror 3600
  • Accept a trust invite: /mesh join <invite-code>
  • View active trust links: /mesh links

Optional: create a second Hermes profile​

If you want a second Hermes profile that inherits runtime configuration from an existing one, Hermes already supports that directly:

hermes profile create secondary-profile --clone
# or choose an explicit source profile
hermes profile create secondary-profile --clone --clone-from primary-profile

This is the current replication-friendly profile path:

  • it copies profile-scoped config/auth surfaces from the source profile
  • it is lighter than --clone-all
  • when the source profile has replication-eligible local memory, Hermes seeds a small starter packet for the new profile

That is useful for next-step runtime expansion, but it is not required for the minimum core bring-up path above.

Stop services​

./scripts/dev-down.sh

Docker options​

Single-stack Docker run for the core local stack:

export AGENT_MESH_OPERATOR_TOKEN=replace-with-a-long-random-token
./scripts/ensure-docker-volume-dirs.sh
docker compose -f ./docker-compose.yml up --build -d

The default Docker bind root for this path is ./.docker-data relative to the repo root.

Experimental pseudo-multihost topology with Hermes edges:

docker compose -f ./docker-compose.pseudomultihost.yml up --build -d

Use the pseudo-multihost stack for stress and soak validation, not as the default release quickstart.