Run VS Agent on your computer
Start here, before you rent a server. Docker runs VS Agent, its database and its cache on your machine; an ngrok tunnel gives the agent the public HTTPS origin that wallets, peer agents and the indexer need to reach it. On testnet the agent behaves like a deployed one: it creates its DID, obtains its ECS credentials and resolves as trusted.
This setup is for learning and testing. The DID is bound to the tunnel's hostname, so the agent you later deploy under your own domain has a new DID, and the trust steps are redone for it.
Goal
A VS Agent on your computer whose DID, did:webvh:<scid>:<your-ngrok-domain>, resolves from the internet and, after the last step, resolves as trusted on testnet.
Prerequisites
- Docker Desktop (macOS, Windows) or Docker Engine with the Compose plugin (Linux), and about 2 GB of free memory.
- On an arm64 machine (Apple Silicon, arm64 Linux), amd64 emulation: the published image is built for amd64. Docker Desktop on a Mac emulates it out of the box (Settings, General, Use Rosetta for x86_64/amd64 emulation); on arm64 Linux, install it once with
docker run --privileged --rm tonistiigi/binfmt --install amd64. - A free ngrok account, with the ngrok agent installed and authenticated (
ngrok config add-authtoken <token>). veranadto generate the agent's account (install the binary), pluscurlandjq.- For the trust steps: a browser wallet (Keplr or Leap) with a funded testnet account and a corporation on testnet that the account can act for, as in the quickstart.
Steps
1. Start a tunnel on a fixed hostname
The agent derives its DID from PUBLIC_API_BASE_URL on its first start and refuses to start once that value changes. A tunnel that gets a new random hostname each run therefore cannot carry a VS Agent. Every free ngrok account comes with one static domain: find yours in the ngrok dashboard under Domains, for example quiet-otter-example.ngrok-free.app, and use it every time.
In a terminal of its own, point the tunnel at the agent's public port and leave it running:
ngrok http 3001 --url https://quiet-otter-example.ngrok-free.app
Older ngrok agents spell the flag --domain quiet-otter-example.ngrok-free.app.
Only port 3001 goes through the tunnel. Port 3000, the admin API, stays on your computer: whoever reaches it controls the agent and its account.
Another tunnel works if it gives you a stable HTTPS hostname, for example a Cloudflare named tunnel on a domain you own; quick tunnels that print a new hostname per run do not.
2. Lay out the files
Create a directory with two files. The Compose file, which binds both agent ports to localhost:
# VS Agent on your own computer: the agent, its PostgreSQL database and Redis.
# Both agent ports are bound to localhost. The public port (3001) reaches the internet
# through an ngrok tunnel; the admin port (3000) never leaves this machine.
# Copy .env.example to .env and fill it in before `docker compose up -d`.
services:
vs-agent:
image: veranalabs/vs-agent:${VS_AGENT_VERSION:?set VS_AGENT_VERSION in .env}
# The published image is built for amd64; arm64 machines (Apple Silicon) run it emulated.
platform: linux/amd64
restart: unless-stopped
env_file: .env
environment:
PUBLIC_API_PORT: "3001"
ADMIN_API_PORT: "3000"
POSTGRES_HOST: postgres
POSTGRES_USER: vsagent
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}
REDIS_URL: redis://redis:6379
# Requests from your terminal arrive through the Docker network gateway.
ADMIN_API_TRUSTED_NETWORKS: 127.0.0.0/8,::1/128,172.16.0.0/12
volumes:
- agent-data:/root/.afj
ports:
- "127.0.0.1:3000:3000"
- "127.0.0.1:3001:3001"
# Lets the agent reach a backend on this computer (EVENTS_WEBHOOK_URL), on Linux too.
extra_hosts:
- "host.docker.internal:host-gateway"
depends_on:
postgres:
condition: service_healthy
redis:
condition: service_healthy
postgres:
image: postgres:16-alpine
restart: unless-stopped
environment:
POSTGRES_USER: vsagent
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}
POSTGRES_DB: vsagent
volumes:
- postgres-data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U vsagent"]
interval: 5s
timeout: 3s
retries: 20
redis:
image: redis:7-alpine
restart: unless-stopped
volumes:
- redis-data:/data
healthcheck:
test: ["CMD-SHELL", "redis-cli ping"]
interval: 5s
timeout: 3s
retries: 20
volumes:
agent-data:
postgres-data:
redis-data:
The environment, copied to .env. Replace quiet-otter-example.ngrok-free.app with your domain everywhere, and set your corporation id:
# ---- image ------------------------------------------------------------------------
# A tag from https://hub.docker.com/r/veranalabs/vs-agent/tags
VS_AGENT_VERSION=v2.0.0-dev.116
# ---- identity and corporation -------------------------------------------------
# The corporation this agent acts for (its id on the registry, from the Frontend).
VERANA_CORPORATION_ID=
# BIP-39 mnemonic of the agent's own account. Generate a fresh one; never commit this file.
VERANA_ACCOUNT_MNEMONIC=
# ---- network --------------------------------------------------------------------
VERANA_CHAIN_ID=vna-testnet-1
VERANA_RPC_ENDPOINT_URL=https://rpc.testnet.verana.network
VERANA_INDEXER_BASE_URL=https://idx.testnet.verana.network
# The testnet ECS ecosystem DID, from Environments and endpoints.
TRUSTED_ECS_ECOSYSTEM_DIDS=did:webvh:QmaG8Zk91utJCRpHZ6ruVKwedNEWXUm1vnXvttf6pENZHM:council.testnet.verana.network
# ---- the service --------------------------------------------------------------------
# Your static ngrok domain. The DID is derived from it on first start: never change it.
PUBLIC_API_BASE_URL=https://quiet-otter-example.ngrok-free.app
AGENT_PUBLIC_DID_METHOD=webvh
AGENT_MODE=standalone
# Claims of the ECS Service credential the agent issues to itself.
ECS_CLAIMS_SERVICE_NAME=My Local Test Service
ECS_CLAIMS_SERVICE_TYPE=WEB_PORTAL
ECS_CLAIMS_SERVICE_DESCRIPTION=A VS Agent running on a developer's computer, for testing.
ECS_CLAIMS_SERVICE_MINIMUM_AGE_REQUIRED=0
# Placeholders served by the agent itself, under your ngrok domain.
ECS_CLAIMS_SERVICE_LOGO_URI=https://quiet-otter-example.ngrok-free.app/vt/default/logo.svg
ECS_CLAIMS_SERVICE_TERMS_AND_CONDITIONS_URI=https://quiet-otter-example.ngrok-free.app/vt/default/terms.html
ECS_CLAIMS_SERVICE_PRIVACY_POLICY_URI=https://quiet-otter-example.ngrok-free.app/vt/default/privacy.html
# Claims the agent proposes for its ECS Organization credential (the validator may adjust them).
ECS_CLAIMS_ORG_NAME=Example Company Ltd
ECS_CLAIMS_ORG_LOGO_URI=https://quiet-otter-example.ngrok-free.app/vt/default/logo.svg
ECS_CLAIMS_ORG_REGISTRY_ID=12345678
ECS_CLAIMS_ORG_ADDRESS=1 Example Street, Example City
ECS_CLAIMS_ORG_COUNTRY_CODE=CH
# ---- optional ---------------------------------------------------------------------
# A backend on this computer receives events at host.docker.internal:
# EVENTS_WEBHOOK_URL=http://host.docker.internal:4000/vs-agent/events
AGENT_LOG_LEVEL=info
ADMIN_API_LOG_LEVEL=info
# ---- database ----------------------------------------------------------------------
POSTGRES_PASSWORD=change-me
TRUSTED_ECS_ECOSYSTEM_DIDS is the testnet value from Environments and endpoints. The *_URI claims point at placeholders the agent serves itself; see Configuration walk-through before you replace them.
3. Create the agent's account
The agent signs its own transactions with VERANA_ACCOUNT_MNEMONIC. Generate a fresh account for it:
veranad keys add local-agent --keyring-backend test
The command prints the address and the mnemonic. Put the mnemonic in .env, keep the address (a fresh agent also logs it at start, in a warning that the account is unfunded), and never commit the file. Send the address a few test coins from your wallet: the faucet only funds an account that signs its challenge, which is your wallet's, not the agent's.
4. Start the agent
docker compose up -d
docker compose logs -f vs-agent
The first start creates the DID and publishes its DID Document; later starts load them from the volumes. Under emulation the first start takes a minute or two longer.
5. Make it trusted
Continue with the quickstart from step 3, Apply for the ECS Organization credential, to step 5, Check that you are trusted. Every admin API command there runs unchanged against http://127.0.0.1:3000.
Keep the computer awake and the tunnel running while the onboarding process is underway: the validator's agent talks to yours over DIDComm, through the tunnel.
Verify
On your computer, then from the internet:
curl -s http://127.0.0.1:3000/v2/agent/health/ready # 200 once the agent caught up with the indexer
curl -s http://127.0.0.1:3000/v2/agent/info | jq # did, version
curl -s https://quiet-otter-example.ngrok-free.app/.well-known/did.jsonl | tail -1 | jq -r .state.id # the same DID, through the tunnel
did.jsonl is the DID log of did:webvh; its last entry is the current DID Document. The agent also serves did.json, the plain did:web form of the same document, whose id starts with did:web:.
After step 5, the trust check reports trusted: true:
#!/usr/bin/env bash
# Resolves the agent's DID on the testnet indexer and prints the trust verdict.
# Usage: check-trusted.sh <did> [indexer base url]
set -euo pipefail
DID="${1:?did}"
IDX="${2:-https://idx.testnet.verana.network}"
curl -sS -X POST "$IDX/v4/verifiable-trust/resolve" \
-H 'content-type: application/json' \
-d "{\"did\":\"$DID\",\"ecsCredentials\":true,\"participations\":{\"states\":[\"ACTIVE\"]}}" \
| jq '{did, trusted, evaluatedAtTime, expiresAtTime,
ecs: [.ecsCredentials[]? | {schema: .ecsSchema, name: .credentialSubject.name}],
accreditations: [.participations[]? | {role, credentialSchemaId, ecosystemId, state}]}'
Stop, restart, start over
- Stop:
docker compose stop, then stop ngrok. While stopped, nobody can reach the agent or fetch its DID Document. - Restart: start ngrok on the same domain first, then
docker compose start. The agent keeps its keys, DID and credentials in the volumes and catches up with the indexer. - Start over:
docker compose down -vdeletes the volumes, and with them the keys, the DID and the credentials. The next start creates a new DID, and the trust steps start again for it.
Move to a server
When everything works, deploy on a server under your own domain: Docker Compose on one VM or Kubernetes with Helm. The .env carries over, except PUBLIC_API_BASE_URL and the *_URI claims. Generate a new mnemonic for the server agent, so that two agents never sign with the same account, and apply for its credentials with its new DID.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
docker compose up fails with "port is already allocated" | Another program on your computer listens on 3000 or 3001, often a web development server | Change the host side of the mapping, for example 127.0.0.1:3010:3000, and use that port in the commands; for the public port, point ngrok at the new port |
The agent exits at once with exec format error | An arm64 machine without amd64 emulation | Enable emulation, see the prerequisites |
| Agent exits saying the DID location differs | ngrok runs on another hostname, or PUBLIC_API_BASE_URL was edited | Restart ngrok on your static domain and restore the original value |
did.jsonl through the tunnel answers with an ngrok error page | The tunnel runs but the agent does not answer on port 3001 | Check docker compose ps and the logs; the tunnel must target the host port of the public API |
| After sleep or a network change, the logs show connection timeouts while your computer is online | Docker lost its outbound route | docker compose down && docker compose up -d; the volumes are kept |
No flow shows up in /v2/vt/flows after you joined | The agent was stopped when the accreditation was created and did not pick it up | docker compose restart vs-agent; the agent looks for pending accreditations at start |
| A browser shows ngrok's warning page instead of your logo or terms | The ngrok free plan answers some browser requests with an interstitial page | Host those resources at another stable HTTPS URL, before the credentials are issued: changing a URI later changes its digest |
Next
- Verify a peer before you connect, open DIDComm connections, then issue and verify credentials, all against your local agent.
- What VS Agent needs to run, before you deploy on a server.