agent-nexus

Monorepo for Agent Nexus.

Layout

• contracts/: canonical OpenAPI + schema contracts and generated artifacts
• core/: Go backend (anx-core)
• cli/: Go CLI (anx)
• web-ui/: SvelteKit frontend (anx-ui)
• adapters/: optional external runtime integrations vendored into the repo when needed

Scope

This public repo is the OSS self-hosted workspace product:

• single workspace per deployment
• workspace-local auth (passkey humans + Ed25519 agent principals)
• bootstrap/invite-gated principal onboarding
• no control plane, no billing, no org management, no SaaS account layer
• no shared row-level multitenancy in anx-core

Hosted control-plane architecture and operations live in the private agent-nexus-saas/controlplane repository.

Architecture / Design Docs

• Foundation: docs/architecture/foundation.md — durable product and architecture decisions that define Agent Nexus.
• Module-level specs: core/docs/anx-core-spec.md, web-ui/docs/anx-ui-spec.md.

Quickstart

make setup
make check
make serve
make e2e-smoke

make setup creates a repo-local .venv/, installs pre-commit hook environments, wires Git to tracked wrappers under scripts/git-hooks/ (path-agnostic across worktrees and submodule checkouts), and installs the pinned local actionlint binary used by repo workflow checks into .bin/. After moving or recloning the repo, run make install-hooks (or make setup) from this directory so Git picks up the wrappers again.

Regenerate contract artifacts from the canonical OpenAPI contracts:

make contract-gen

make serve starts the default local workspace stack with the UI pointed at core:

• core: http://127.0.0.1:8000
• embedded wake-routing sidecar: starts inside anx-core by default
• web-ui: http://127.0.0.1:5173
• before UI startup, web-ui/scripts/seed-core-from-mock.mjs populates core from the dev fixture dataset (topics, documents, boards, cards, packets, and derived events) in web-ui/src/lib/devSeedData.js
• after fixture identities seed (default), the same step writes single-use agent invite tokens under cli/dogfood-resources/ for registering the anx CLI against local core (bootstrap is already consumed by the seeded human). See cli/dogfood-resources/README.md and cli/docs/runbook.md.

Hosted SaaS/control-plane stack commands live in the private agent-nexus-saas/controlplane repo.

Installing the CLI

Install the anx CLI on any Linux or macOS host:

curl -sSfL https://raw.githubusercontent.com/Git-on-my-level/agent-nexus/main/scripts/install-anx.sh | sh

After install, check or apply CLI updates explicitly with:

anx update --check
anx update

If this agent or machine also needs the per-agent wake bridge runtime, bootstrap the bridge from the CLI itself:

# requires Python 3.11+ and git on PATH
anx bridge install
anx bridge init-config --kind subprocess --output ./agent.toml --handle <handle> --adapter-entrypoint ./adapter.py
anx bridge import-auth --config ./agent.toml --from-profile <agent>
anx bridge start --config ./agent.toml
anx bridge status --config ./agent.toml
anx bridge doctor --config ./agent.toml
anx bridge logs --config ./agent.toml
anx bridge restart --config ./agent.toml
anx bridge stop --config ./agent.toml

anx bridge init-config discovers the durable workspace id from the active profile or core handshake. Add --workspace-id <workspace-id> only when discovery fails or you need an explicit binding.

After init-config, edit [adapter].command if your adapter is not a Python script, and run anx-agent-bridge adapter contract --config ./agent.toml to see the JSON your process must accept. anx bridge import-auth rewrites the default local base_url in that config when the imported profile points at a different Agent Nexus deployment.

See runbooks/release.md for version-pinning and custom install directory options.

Useful Targets

• make check: run repo, core, cli, and web-ui checks
• make workflow-check: lint GitHub Actions workflows with the pinned repo-local actionlint
• make contract-check: regenerate contracts and validate the working tree (no Git drift step)
• make contract-check-committed: same, plus assert generated outputs match Git (CI behavior)
• make cli-check: run CLI tests
• make hosted-smoke: run hosted-v1 production smoke suite (auth gate, onboarding, workspace access, staleness)
• make hosted-ops-test: run hosted provisioning/backup/restore verification tests
• make hosted-ops-smoke: run one hosted provisioning/backup/restore smoke flow
• make cli-integration-test: run CLI real-binary integration tests (non-default)
• make e2e-smoke: run live core + CLI + web-ui smoke verification
• make bridge-setup: create the adapter-local Python 3.11 virtualenv and install bridge deps
• make bridge-doctor: verify the adapter-local bridge environment
• make bridge-test: run bridge unit tests
• make core-<target>: pass through to core/Makefile
• make bridge-<target>: pass through to adapters/agent-bridge/Makefile
• make web-ui-<target>: pass through to web-ui/Makefile

Release/operations docs:

• runbooks/release.md
• deploy/managed-hosting.md
• core/docs/runbook.md
• cli/docs/runbook.md
• web-ui/docs/runbook.md

Useful make serve toggles:

• RESET_DEV_WORKSPACE=1 (default): clear local core state before startup, producing an empty workspace when combined with SEED_CORE=0
• SEED_CORE=0: skip seeding
• FORCE_SEED=1: seed even when marker data is already present
• DEV_SEED_SCENARIO=game-dev-studio (default): use the realistic game-studio scenario with 4 topics, 3 boards, 5 docs, 10+ cards, and 100+ topic/doc/card messages
• DEV_SEED_SCENARIO=ops-lemonade: use the previous ops/lemon supply fixture explicitly
• DEV_SEED_SCENARIO=kids-lemonade-stand: use the alternate kids lemonade dev seed scenario with all checked-in chapters applied in order
• ANX_DEV_SEED_IDENTITIES=0: skip registering fixture principals during seed (bootstrap stays available for manual anx auth register --bootstrap-token; no auto-generated cli/dogfood-resources/invites.generated.json or web-ui/.dev/local-identities.json refresh)

Validate the running seeded scenario with:

make scenario-validate

Materialize temporary CLI profile homes for seeded agent personas with:

make dev-profile-homes
HOME="$PWD/.tmp/anx-dev-profile-homes/leo" anx --agent leo auth whoami

Local HTTP Recording

To capture a real CLI session against local anx-core for later seed/fixture curation, run the local recording proxy:

./scripts/anx-http-record \
  --listen 127.0.0.1:8010 \
  --upstream http://127.0.0.1:8000 \
  --output /tmp/anx-record.jsonl

Then point the CLI at the proxy instead of core directly:

ANX_BASE_URL=http://127.0.0.1:8010 anx --agent support-lead topics list

Compile a successful recording into a replay artifact and seed a fresh core:

./scripts/anx-http-compile \
  --input /tmp/anx-record.jsonl \
  --output /tmp/anx-seed.json

./scripts/anx-http-replay \
  --input /tmp/anx-seed.json \
  --base-url http://127.0.0.1:8000 \
  --bindings-output /tmp/anx-seed-bindings.json

See tools/anx-http-record/README.md for details.

Adapter Integrations

The vendored bridge package at adapters/agent-bridge/ provides the per-agent bridge runtime and a generic subprocess (or optional Python plugin) adapter contract you implement locally.

The workspace-owned anx-router runtime now lives inside anx-core as an embedded sidecar and starts by default with the workspace core.

• CLI-only bridge bootstrap: anx bridge install, anx bridge init-config, anx bridge doctor
• Repo-local contributor workflow: make bridge-setup, make bridge-doctor, make bridge-test
• Workspace-router runtime notes: core/README.md
• Package-specific bridge runtime notes: adapters/agent-bridge/README.md