Ghost in the shell

Many AI agents on one host — each with personality, purpose, rules, and tools. Agents think, act, observe, and remember. They coordinate through schedules, channels (including Slack), inter-agent messaging, and optional Ghost Whisper evaluation on the heartbeat path.

ghost.bizs.app — overview, worlds, roadmap, contribute

---

Documentation

• docs/design.md — architecture and a map to the HTTP/WebSocket API, storage, scheduler, skills, channels, and more.
• ghost.bizs.app — the same ideas in a lighter form, with screenshots and navigation for newcomers.

Prerequisites

• Docker — for development, you only need Docker; it is enough to run the local stack below.

Optionally, you can run things directly on the host — both the Go engine and the dashboard.

Working on the Go server or the dashboard from source needs Go and Node.js (versions in go.mod and .tool-versions). See the checklist in CONTRIBUTING.md.

Many deployments use PostgreSQL for durable memory, schedules, and knowledge; the Docker stack includes Postgres. File-backed options exist for simpler setups — see docs/storage.md.

Get started

Docker (simplest): from the repository root:

make up

This uses docker/docker-compose.yml and starts Postgres, Ghost, the dashboard, and local devtools.

When the stack is up, open the dashboard at http://localhost:5173. Ghost begins idle (no world loaded yet). Load a world from the dashboard, or call POST /api/admin/worlds/load — see docs/world-loader.md. If you prefer a world file at process start, set GHOST_CONFIG in docker/env.ghost; that step is optional.

Secrets and config (optional to do by hand): you do not need to edit files first. With Docker and the usual flow (idle Ghost, load a world from the dashboard), the setup path in the UI walks you through provider keys, Slack, and the rest. Anything you save under Dashboard → Config wins over matching variables in the Ghost process when both exist.

If you like boot-time defaults in the container instead, copy or adjust docker/env.ghost (admin key, URLs, optional API keys, etc.).

Example worlds: configs such as config/world0-standalone-complex.yaml assume OpenAI with gpt-5.4-mini. Set OPENAI_API_KEY via the environment or the dashboard before running them.

For more Compose variants and Make targets, see Makefile and docker/.

License

MIT License.

Security

To report a security vulnerability, follow SECURITY.md. Please do not file sensitive issues in public GitHub issues.

Contributing

Contributions are welcome. Read CONTRIBUTING.md and CODE_OF_CONDUCT.md before opening a pull request. Questions and coordination: Contribute on the site and the contact there.