🏁 Get started

AgentConnect OSS is the open-source, self-hosted AgentConnect stack. Docker Compose starts the Web console, Control Plane, Relay, Setup Server, and PostgreSQL. Agent execution remains in daemons on the machines that own the workspaces and runtime credentials.

The source is available in the AgentConnect repository.

Before you start

You need:

• Docker Desktop, OrbStack, or Docker Engine;
• Docker Compose v2 (docker compose version); and
• Git.

Published AgentConnect images currently target linux/amd64. Docker Desktop and OrbStack can run them with emulation on Apple Silicon.

1. Start the stack

git clone https://github.com/agentconnect-md/agentconnect.git
cd agentconnect
docker compose up -d --pull always

To build the images from the checkout instead of pulling the published ones, run docker compose up -d --build. Every service in compose.yaml carries a build definition, and the built images take the tags the stack already references. The build targets linux/amd64 like the published images, so it is emulated and slow on Apple Silicon.

The first run starts PostgreSQL 18, applies the database migrations, initializes the local no-auth organization, and starts the application services. It adds no sample data. The built-in agentconnect agent is enabled by default and can be disabled in Setup.

Check the stack:

docker compose ps --all

postgres, control-plane, relay, setup-server, and web should be running. migration-files and migrate should show Exited (0); they are successful one-shot jobs.

2. Open AgentConnect

Open http://localhost:3000.

The default stack binds its ports to 127.0.0.1, and sign-in is disabled. Keep this mode local.

You can check the service probes directly:

curl http://localhost:8080/readyz
curl http://localhost:8090/readyz

3. Connect a daemon

The Compose stack deliberately does not run the daemon in a container. Keeping it on the host gives agents access to local repositories, runtime launchers, and existing Claude or Codex authentication.

In the Web console:

1. Open Daemons and choose Add daemon.
2. Copy the one-time command.
3. Run that exact command on the machine that should host the agents.

The daemon connects to the Control Plane and Relay with outbound connections. If it runs on another machine, configure host-reachable URLs first; see Network and public URLs.

Guided setup

Past the local stack — sign-in, public URLs, provider apps, and production hardening — a guided path helps. The repository ships a setup skill for Claude Code at .claude/skills/agentconnect-setup: open Claude Code in the checkout and ask it to set up AgentConnect, and it runs this page and the deployment pages as an interactive tutorial, verifying each checkpoint before continuing. It never asks you to paste secrets into chat.

The sections below cover the same ground by hand, and stay the reference whether or not you use the skill.

Optional: add local sign-in

The repository includes a Logto OSS overlay for evaluating real sign-in without setting up DNS or TLS:

docker compose -f compose.yaml -f compose.logto.yaml up -d

Then open:

• Setup: http://localhost:8091
• Logto Console: http://localhost:3002
• AgentConnect: http://localhost:3000

Continue with Logto authentication and use Google for the shortest local sign-in path. The local overlay uses a separate Logto database in the same PostgreSQL service and remains bound to loopback.

When you use the overlay, keep both -f arguments in later up, pull, and down commands.

For hosted production sign-in, skip the overlay and connect a Logto Cloud tenant instead.

Logs and updates

Follow the stack:

docker compose logs -f

Pull current images and apply migrations:

docker compose pull
docker compose up -d

If you created compose.env, add --env-file compose.env to each command. Pin AGENTCONNECT_VERSION to a release tag for reproducible deployments.

Stop or reset

Stop the stack while preserving its database:

docker compose down

Delete the database and return to an empty installation:

docker compose down --volumes

This permanently deletes Control Plane and Setup Server data in the Compose database. Daemon-local workspaces and transcripts are outside this volume and are not deleted.

What the stack includes

The Relay is included so GitHub, webhooks, webchat, and HTTP bot callbacks work without changing the stack. Direct Slack Socket Mode, Telegram, Discord, and Lark / Feishu connections continue to run between the daemon and their providers.

Deployment boundary

The bundled Compose topology is intended for local evaluation and single-host deployment. Before publishing it to a network, configure real sign-in, replace the default secrets, use TLS, back up PostgreSQL, and provide reverse-proxy support for WebSockets.

Agent execution remains daemon-local. The Control Plane stores coordination data rather than message bodies, attachment bytes, workspaces, or live agent-session streams. See How it works.

Next

• Deployment and configuration
• Configure authentication with Logto
• Install the daemon as a service