Troubleshooting

A machine won’t start, or its port is in use

The daemon listens on 127.0.0.1:6780 by default.

Fix: Another daemon may already be running on that port. Run cyborg daemon status to see it, then cyborg daemon stop, or choose another port with cyborg daemon start --port <port> (or PASEO_LISTEN). When you run from a source checkout, pnpm dev:cyborg uses port 6780 for the daemon and 5173 for the UI, while plain pnpm dev starts only the daemon, on port 6768.

An update did not take effect on a machine

The machine reports the new version but behaves like the old one.

Fix: A daemon that is already running ignores a start command unless you pass --replace. Use cyborg daemon update, or cyborg daemon start --replace. A systemd unit must use cyborg daemon start --replace --foreground. See the CLI reference.

Cannot find module / dependencies out of sync (source checkout)

Imports fail after merging or switching branches.

Fix: Run pnpm install to reinstall workspace dependencies, then restart the daemon.

Database migrations fail or hang

Fix: Run migrations with the supported command, pnpm db:migrate from a checkout, or docker compose run --rm migrate from deploy/ in a Docker install. Pending migrations are applied and applied ones are skipped, so it is safe to re-run. Migration files live in packages/server/src/server/cyborg/db/drizzle/. If a single file must be applied by hand, use psql "$DATABASE_URL" -f <file> and do not paste the connection string into shared logs. Only the relay’s shared PostgreSQL database needs migrations.

Postgres: “The server does not support SSL connections”

The relay negotiates TLS to any non-loopback database host by default, and a Postgres without TLS refuses it.

Fix: Append ?sslmode=disable to DATABASE_URL, or set PG_SSL_MODE=disable. For a managed database whose certificate you want verified, set PG_SSL_MODE=verify-full. See Docker.

docker compose up fails on port 6379

The bundled Redis is published on host port 6379, and another Redis is already listening there.

Fix: Stop the other Redis, or change the Redis port mapping in deploy/docker-compose.yml.

An agent never goes online / no response

You created an agent but it never streams output.

Fix: Check: 1) the provider (Claude Code, Codex, GitHub Copilot, OpenCode or Pi) is installed and signed in on that machine (cyborg provider:list and cyborg provider:sign-in), 2) the agent’s working directory exists, 3) the daemon’s logs for spawn errors. Agents run as processes on the machine’s own computer. A stuck session can be restarted in place with cyborg agent:reload.

Messages not syncing across machines

Messages appear locally but teammates on other machines don’t see them.

Fix: Check: 1) the machine is connected to the relay (cyborg daemon doctor shows the relay link and online state), 2) the relay’s database is reachable (DATABASE_URL on a self-hosted relay), 3) the relay logs for the relay_subscribed confirmation. Each machine only receives the workspaces it belongs to.

An agent won’t spawn (pi not found)

cyborg cybo:spawn fails to launch the agent on the machine.

Fix: agents on the Pi provider need the pi binary on the machine’s PATH. Install it from the machine’s Providers list, or with cyborg provider:install <workspace-id> pi --daemon <machine-id>, then cyborg provider:refresh <workspace-id> pi --daemon <machine-id>. Claude and Codex agents do not need pi.

The relay refuses to boot

The relay exits at startup complaining about the JWT secret.

Fix: CYBORG7_JWT_SECRET must be set to a strong value of at least 32 characters. The relay refuses to run on a public interface with a missing, short or public-default secret. Generate one with openssl rand -hex 32, or run tools/gen-selfhost-secrets.sh deploy/.env.

Asset upload (avatars, attachments) fails

Uploads error out on a self-hosted relay.

Fix: The default storage backend is S3 (ASSETS_BACKEND=s3): set S3_ASSETS_BUCKET, S3_ASSETS_REGION and the credentials on the relay (with Docker Compose, in deploy/.env; the relay service loads it, Compose 2.24 or newer), and check the relay logs for the presign step. To avoid S3, set ASSETS_BACKEND=fs (the relay’s own disk) or point ASSETS_S3_ENDPOINT at an S3-compatible server such as MinIO. See Configuration.