Synx — Quickstart (self-host)

Synx is a self-hosted harness: you run the stack on your own machine/server and operate it with your key. Nothing runs on our servers.

Topology

• Infra in Docker — postgres, redis, VVM (deterministic core), EEAPI (gate + ingress).
• Bare-metal AVM — the agent runtime ("the hands"). Runs directly on the host for native access to your filesystem and local tools, with every action governed by the gate.

Prerequisites

• Docker (with docker compose).
• A model provider API key (Groq/OpenAI/OpenRouter/Anthropic) — or local Ollama.
• Go is not required: the AVM and the CLI ship as prebuilt binaries.

Bring it up

git clone git@github.com:peiblow/synx-init.git && cd synx-init
make init     # installs binaries (avm+synx), generates YOUR key, prepares .env and contract.env
# edit .env   → uncomment and fill in your provider key (e.g. GROQ_API_KEY=...)
make up       # docker infra + bare-metal AVM

make ps shows status; make logs (docker) and make avm-logs (AVM).

Configure your contracts

Contracts declare config via getEnv("X"). Those keys are yours — they go in contract.env (never in .env.example, never committed). Deploy lists what's missing:

synx deploy ./my-contract     # reports which getEnv keys the contract requires
# fill those keys in contract.env
make restart-eeapi            # mounts the triggers of the freshly deployed contract

getEnv resolves at runtime inside the VVM (actions) and the EEAPI (triggers) — the secret never enters the artifact and the same contract runs in any environment.

Full CLI reference (build, deploy, ship, env, keys, synx.toml): see CLI.md.

fs-trigger (optional)

If one of your contracts uses an fs-trigger, the EEAPI watcher needs to see your directory:

cp docker-compose.override.yaml.example docker-compose.override.yaml
# point the mount at your dir; the AVM (bare-metal) writes to the host without any mount

Security

• Never commit .env, contract.env or tokens (already covered by .gitignore).
• Every self-hoster has their own key (make init generates it; ~/.synx/deploy.key).

Update

git pull && make update   # re-fetches the binaries for the repo's new version
make down && make up

Dev (contributing)

Development happens in the source monorepo, which nests this repo and adds the build targets (make dev, make release) plus a compose override that builds vvm/eeapi from source instead of pulling published images.