Configuration

AgentCTX is configured through three layers: the actx.yaml config file, environment variables, and optional secrets management via 1Password.

actx.yaml

Created by actx init, this file lives at .context/actx.yaml in your project root.

version: "0.1.0"
project: my-agent-project

# MCP backend servers
backends:
  - id: github
    cmd: "npx -y @modelcontextprotocol/server-github"
    roles: [code, issues]
    transport: stdio
    lazy: true

  - id: filesystem
    cmd: "npx -y @modelcontextprotocol/server-filesystem /workspace"
    roles: [files]
    transport: stdio

# Context planes
planes:
  tools:
    enabled: true
  knowledge:
    enabled: true
    sources: ["docs/", "src/"]
  skills:
    enabled: true
    sources: [".agent/"]
  memory:
    enabled: true

# Entry points (for non-MCP clients)
entry:
  httpPort: 3100
  tcpPort: 3101
  httpEnabled: true
  tcpEnabled: true

Backend Configuration

Each backend entry defines an MCP server:

Field	Type	Default	Description
`id`	string	required	Unique identifier for the backend
`cmd`	string	required	Command to spawn the server
`roles`	string[]	`["default"]`	Role scoping — limits which tools agents can access
`transport`	string	`"stdio"`	Transport type: `stdio`, `sse`, or `http`
`lazy`	boolean	`true`	If true, server spawns on first tool query
`cwd`	string	—	Working directory for the command

Plane Configuration

Plane	Sources	Description
`tools`	—	Always available. Discovers tools from registered backends
`knowledge`	directories	Indexes files from specified source directories
`skills`	directories	Loads `.md` skill files from specified paths
`memory`	—	Persistent storage. Requires SurrealDB for cross-session

Environment Variables

Environment variables override actx.yaml settings and configure infrastructure connections.

Database (SurrealDB)

Variable	Default	Description
`SURREAL_URL`	`http://localhost:8000`	SurrealDB connection URL
`SURREAL_NS`	`agentctx`	SurrealDB namespace
`SURREAL_DB`	`main`	SurrealDB database name
`SURREAL_USER`	`root`	SurrealDB username
`SURREAL_PASS`	`root`	SurrealDB password

Messaging (NATS)

Variable	Default	Description
`NATS_URL`	`nats://localhost:4222`	NATS server URL
`NATS_MONITOR_URL`	`http://localhost:8222`	NATS monitoring endpoint

LLM Providers

Variable	Description
`ANTHROPIC_API_KEY`	Anthropic API key (for ctx-gateway LLM interception)
`OPENAI_API_KEY`	OpenAI API key (for ctx-gateway LLM interception)

Runtime

Variable	Default	Description
`NODE_ENV`	`development`	Set to `production` for optimized builds
`MOCK_MCP_URL`	—	URL of mock MCP backend (development/testing)

Secrets Management

AgentCTX integrates with 1Password for secure credential storage.

Setup

# Configure 1Password Service Account
actx auth

# Or set the token directly
export OP_SERVICE_ACCOUNT_TOKEN=ops_...

How It Works

With a valid Service Account token:

actx init fetches the project salt from 1Password vault instead of generating a local one
Credentials are never stored in plaintext on disk
The encrypted token is stored at .context/.keys/sa-token.enc

Without 1Password:

A local project.salt file is generated (suitable for development)
A warning is displayed on startup

Vault References

Configuration values can reference 1Password vault items using the op:// prefix:

backends:
  - id: production-db
    cmd: "node db-server.js"
    env:
      DATABASE_URL: "op://Infrastructure/production-db/url"

.context/ Directory Structure

.context/
├── actx.yaml              # Gateway configuration
├── .keys/
│   ├── ed25519.key         # Agent signing keypair (Ed25519)
│   ├── ed25519.pub         # Public key
│   ├── project.salt        # Convergent encryption salt
│   └── sa-token.enc        # 1Password SA token (encrypted)
├── objects/                # Content-addressed store (SHA-256)
├── refs/                   # Reference pointers
├── translations/           # Signed sidecar translations
└── logs/                   # Operation audit logs

Next Steps

Quick Start → — try AgentCTX with your first project
Adding MCP Backends → — configure multiple backend servers
Deployment → — production deployment with Docker