AgentCircuits.Server 0.7.0

AgentCircuits.Server

Turnkey host for AgentCircuits Portal API, SignalR hubs, and UI endpoints. This package provides a runnable server that wires AgentCircuits.Portal + AgentCircuits.UI together using configuration.

Installation

NuGet Package

dotnet add package AgentCircuits.Server

Then create a minimal host:

// Program.cs
AgentCircuits.Server.Program.Run(args);

Docker Image

docker pull ghcr.io/agent-circuits/agentcircuits-server:latest

docker run -p 8080:8080 \
  -v ./data:/data \
  -e AGENTCIRCUITS__PROVIDERS__ANTHROPIC__API_KEY=sk-ant-... \
  ghcr.io/agent-circuits/agentcircuits-server:latest

Self-Contained Executable

Download from GitHub Releases or build locally:

./publish.sh linux-x64        # Linux
./publish.sh win-x64          # Windows
./publish.sh osx-arm64        # macOS Apple Silicon

Output is in publish/<runtime>/.

Configuration

The server reads appsettings.json from the working directory. Key settings:

Environment Variables

Use __ as section separator:

AGENTCIRCUITS__STORAGE__MODE=Sql
AGENTCIRCUITS__STORAGE__CONNECTIONSTRING=Host=localhost;Database=agentcircuits
AGENTCIRCUITS__PROVIDERS__ANTHROPIC__ENABLED=true
AGENTCIRCUITS__PROVIDERS__ANTHROPIC__API_KEY=sk-ant-...

Local Development

Run from the monorepo root:

ASPNETCORE_ENVIRONMENT=Development dotnet run --project agentcircuits.server/src/AgentCircuits.Server.csproj

The Development environment loads appsettings.Development.json, which contains the correct storage path and other local settings.

This builds UI assets automatically (requires Node.js). To skip UI builds:

dotnet build -p:SkipNpmBuild=true

Docker

From GHCR (recommended)

docker run -p 8080:8080 \
  -v ./data:/data \
  -e AGENTCIRCUITS__PROVIDERS__ANTHROPIC__API_KEY=sk-ant-... \
  ghcr.io/agent-circuits/agentcircuits-server:latest

Run with PostgreSQL (manual)

docker network create ac-net

docker run -d --name ac-postgres \
  --network ac-net \
  -e POSTGRES_DB=agentcircuits \
  -e POSTGRES_USER=agentcircuits \
  -e POSTGRES_PASSWORD=agentcircuits \
  -p 5432:5432 \
  postgres:16

docker run -d --name ac-server \
  --network ac-net \
  -p 8080:8080 \
  -e AGENTCIRCUITS__STORAGE__MODE=Sql \
  -e AGENTCIRCUITS__STORAGE__CONNECTIONSTRING='Host=ac-postgres;Port=5432;Database=agentcircuits;Username=agentcircuits;Password=agentcircuits' \
  -e AGENTCIRCUITS__STORAGE__SCHEMA=public \
  ghcr.io/agent-circuits/agentcircuits-server:latest

The server runs migrations automatically on startup when Storage:Mode=Sql.

Build from Server Repo

docker build -t agentcircuits-server:local .

This path builds from published NuGet dependencies declared by agentcircuits.server/src/AgentCircuits.Server.csproj.

Build from Monorepo

# From monorepo root
docker build -f agentcircuits.server/Dockerfile.monorepo -t agentcircuits-server:local .

This path uses local project references and is recommended when validating in-progress monorepo changes.

Note: The monorepo Dockerfile uses -p:SkipNpmBuild=true, so it packages the pre-built agentcircuits.ui/wwwroot assets without running npm run build. If your UI source has changed, rebuild before building the image:

cd agentcircuits.ui && npm run build

Docker Compose

docker compose up

This compose file runs the server in SQL mode against the bundled postgres service. It is the default local app runtime profile (manual Portal/UI/API usage), not the dedicated external test harness profile.

External test harness container (recommended for AC_TEST_SERVER_MODE=external)

AgentCircuits.Server.Tests external mode uses /portal/api/testing/* control endpoints and expects deterministic state. The most reliable setup is a dedicated ephemeral container with testing enabled and in-memory storage.

From monorepo root:

docker rm -f ac-external-server 2>/dev/null || true

docker build -f agentcircuits.server/Dockerfile.monorepo -t ac-current-server:test .

docker run -d --name ac-external-server -p 8080:8080 \
  -e AGENTCIRCUITS__AUTH__PROVIDERS__0=LocalUserId \
  -e AGENTCIRCUITS__AUTH__LOCALUSERID__ENABLED=true \
  -e AGENTCIRCUITS__PORTAL__REQUIREAUTHENTICATION=true \
  -e AGENTCIRCUITS__PORTAL__FORCEADMINFORALLUSERS=true \
  -e AGENTCIRCUITS__PORTAL__LOADPROVIDERCONFIGSFROMSTORAGE=false \
  -e AGENTCIRCUITS__PORTAL__BASEPATH=/portal \
  -e AGENTCIRCUITS__PORTAL__ENABLESPAFALLBACK=true \
  -e AGENTCIRCUITS__FEATURES__A2A=true \
  -e AGENTCIRCUITS__FEATURES__CHANNELS=true \
  -e AGENTCIRCUITS__SESSIONSUMMARISER__ENABLED=false \
  -e AGENTCIRCUITS__STORAGE__MODE=InMemory \
  -e AGENTCIRCUITS__STORAGE__PATH=/data \
  -e AGENTCIRCUITS__TESTING__ENABLED=true \
  ac-current-server:test

curl -s http://127.0.0.1:8080/health

Seed providers/agents from portal-storage

If you are running from the monorepo and want the same providers/agents as file storage:

# from monorepo root
docker compose -f agentcircuits.server/docker-compose.yml exec -T postgres \
  psql -U agentcircuits -d agentcircuits < portal-db/seed_portal_storage_providers_agents.sql

docker compose -f agentcircuits.server/docker-compose.yml restart agentcircuits

Provider configs are loaded on startup, so restart after seeding.

Integration Test Modes

AgentCircuits.Server.Tests supports two runtime modes:

• In-proc (default): the test process starts its own server instance with in-memory storage.
• External: tests run against a real running server (for example Docker + Postgres on http://127.0.0.1:8080).

Run the full matrix in-proc:

dotnet test agentcircuits.server/tests/AgentCircuits.Server.Tests.csproj

Run the full matrix against an external server:

AC_TEST_SERVER_MODE=external \
AC_TEST_EXTERNAL_BASE_URL=http://127.0.0.1:8080 \
dotnet test agentcircuits.server/tests/AgentCircuits.Server.Tests.csproj

Optional external mode variables:

• AC_TEST_EXTERNAL_API_KEY for X-AC-Test-Key when testing endpoints require it.
• AC_TEST_EXTERNAL_USER_ID to control the test harness identity used for /portal/api/testing/* calls.

External mode requires testing control endpoints (AgentCircuits:Testing:Enabled=true) because the suite uses /portal/api/testing/*.

Recommended: run external mode against the dedicated ac-external-server harness container above.

If you prefer compose, add AGENTCIRCUITS__TESTING__ENABLED=true to the service environment and start from a clean DB (docker compose down -v) before running the external suite.

Cleanup for harness runs:

docker rm -f ac-external-server
docker rmi ac-current-server:test

Authentication in Docker

Critical: Without auth configuration, ALL users resolve to userId=null and can see every session. The Docker compose includes LocalUserId auth by default (matching appsettings.Development.json), but any custom deployment must set these env vars:

AGENTCIRCUITS__PORTAL__REQUIREAUTHENTICATION=true
AGENTCIRCUITS__AUTH__PROVIDERS__0=LocalUserId
AGENTCIRCUITS__AUTH__LOCALUSERID__ENABLED=true

Without these, the UI still sends X-AC-UserId headers but the server ignores them (the LocalUserId scheme isn't registered), so all requests are anonymous and session isolation breaks.

For production, replace LocalUserId with Jwt or AzureAd. See Authentication & Authorisation.

Docker Troubleshooting

1. Container starts but host port is unreachable: Use the latest image build from this repo. Dockerfiles set URLS and ASPNETCORE_URLS to http://0.0.0.0:8080 so Kestrel binds to all interfaces in containers.

2. Monorepo Docker build fails with missing compact-prompt.md: Ensure the monorepo root .dockerignore includes: !agentcircuits/src/Resources/compact-prompt.md This markdown file is an embedded resource required by AgentCircuits.

3. SQL data seeded but providers not visible: Provider registration happens at startup. Restart the server container after seeding.

Health Check

Three health endpoints are available (all respect PathBase if set):

• GET /health/live — liveness probe, always returns 200 with {"status":"ok"}
• GET /health/ready — readiness probe, checks SQL connectivity if configured (returns 200 or 503)
• GET /health — alias for /health/live

Publishing

Automated (CI)

Pushing a v* tag triggers:

1. NuGet package published to nuget.org
2. Docker image published to ghcr.io

Manual

# NuGet package
dotnet pack src/AgentCircuits.Server.csproj -c Release -o ./artifacts

# Self-contained executable
./publish.sh linux-x64

# Docker image
docker build -t myregistry/agentcircuits-server:v1.0.0 .
docker push myregistry/agentcircuits-server:v1.0.0

Customisation

For custom tools or services, create your own host project:

AgentCircuits.Server.Program.Run(args, builder =>
{
    builder.Services.AddSingleton<IMyService, MyService>();
});

Links

• AgentCircuits Documentation
• NuGet Package
• Docker Images