Running a server¶
gdc serve runs gdc as a background process that remote
terminal-app clients connect to, and
that exposes a read-only HTTP API for inspecting sessions.
Starting¶
By default it binds to loopback only — reachable from the same machine, nothing else. This is deliberate: expose it further only after you've read Security.
Connect the terminal app to it:
Common options¶
| Flag | Default | Description |
|---|---|---|
--bind <host:port> |
127.0.0.1:8088 |
Address to listen on. |
--profile <name> |
default |
Default profile for new runs. |
--output-style <name> |
— | Default reply style for new runs. |
The bind address can also come from the GDC_SERVE_BIND environment
variable.
Encrypting connections¶
For anything beyond loopback, terminate TLS. gdc serve can use your own
certificate, generate a self-signed one, or obtain certificates
automatically. See TLS for the full set of options.
Exposing beyond the local machine¶
Binding to a non-loopback address makes gdc reachable from the network. Because a gdc server drives an agent that can act on a machine, treat this as you would any powerful service:
- Put it behind a reverse proxy that adds authentication and TLS.
- Restrict who can reach the port (firewall, private network).
- Consider running it in an isolated environment (a container or a dedicated user account).
→ Security
Coordinated work durability¶
If you run coordinated multi-agent work on a server, two settings control what happens to subagents across restarts:
[task]
# After a restart, re-launch subagents that were interrupted mid-run.
resume_interrupted_workers_on_startup = false
# Archive finished subagent records after this many idle seconds
# (0 disables the cleanup).
idle_timeout_secs = 0
On startup the server tidies up subagent records left "running" by a
previous process, marking them interrupted so the view stays consistent.
Set resume_interrupted_workers_on_startup = true to have it pick those
runs back up automatically — useful for batch or CI setups where you'd
rather it resume than wait for a person.
Stopping¶
Stop the server with Ctrl+C (or your process manager). Because every message and action is saved as it happens, an interrupted run can be resumed later — see Sessions & projects.