Coulisse

Coulisse

One YAML file. An OpenAI-compatible server with memory, tools, and multi-backend routing.

Coulisse is a single Rust binary that reads a coulisse.yaml file and spins up an OpenAI-compatible HTTP server. Point your existing SDKs, IDEs, and tools at it like any other OpenAI endpoint — and everything configurable lives in that one YAML file.

Every multi-agent project ends up re-implementing the same plumbing: per-user memory, multi-backend routing, rate limiting, tool integration, multiple system prompts. Coulisse collapses that plumbing into one configurable server.

Quickstart

Install — grab the latest release for your platform:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Almaju/coulisse/releases/latest/download/coulisse-installer.sh | sh

Or build from source:

git clone https://github.com/Almaju/coulisse.git
cd coulisse
cargo build --release

Configure:

coulisse init            # writes a minimal coulisse.yaml (one agent, one provider)
coulisse init --from-example  # full annotated example with every section
# edit coulisse.yaml and drop in an API key

See [examples/](examples/) for realistic multi-agent configs with MCP tools, judges, and triggers.

Run:

./target/release/coulisse
# coulisse listening on http://0.0.0.0:8421

Call it like OpenAI:

curl http://localhost:8421/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-assistant",
    "safety_identifier": "user-123",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Any OpenAI SDK works — just set base_url to http://localhost:8421/v1.

What a config looks like

providers:
  anthropic:
    api_key: ${ANTHROPIC_API_KEY}
  openai:
    api_key: ${OPENAI_API_KEY}

vars:
  footer: "Team wiki: https://wiki.example.com"

memory:
  storage: ./coulisse-memory.db
  user_state: true

mcp:
  hello:
    transport: stdio
    command: uvx
    args: [--from, git+https://github.com/macsymwang/hello-mcp-server.git, hello-mcp-server]

agents:
  - name: claude-assistant
    provider: anthropic
    model: claude-sonnet-4-5-20250929
    preamble: |
      You are a helpful general-purpose assistant.
      ${vars.footer}
    mcp_tools:
      - server: hello

  - name: gpt-assistant
    provider: openai
    model: gpt-4o
    preamble: You are a helpful general-purpose assistant.

triggers:
  - name: daily-check
    type: cron
    schedule: "0 9 * * *"
    agent: claude-assistant
    prompt: "Good morning. Summarise yesterday in five bullets."

Request a specific agent by setting model to its name. Conversation history is kept per safety_identifier.

Features

| | | |---|---| | Multi-agent routing | Each agent has its own provider, model, preamble, and tools — pick one via the model field. | | Per-user memory | Isolated conversation history scoped by safety_identifier, with semantic recall. | | Multi-backend | Anthropic, OpenAI, Gemini, Cohere, Deepseek, Groq. | | OpenAI-compatible | /v1/chat/completions and /v1/models — drop-in for any OpenAI SDK. | | MCP tools | Attach Model Context Protocol servers over stdio or HTTP. Per-agent filtering. | | Async tasks | dispatch_task / tasks_status built-in tools; background worker pool with a studio queue view. | | Triggers | Cron, webhook (POST /hooks/*), and boot triggers fire agents without an HTTP client. | | Sidecars | Declare long-lived helper processes (bridges, listeners) under sidecars: with restart policy. | | Config variables | Top-level vars: block — declare a snippet once, splice it anywhere with ${vars.name}. | | Rate limiting | Per-user token quotas on hour / day / month windows. | | Studio UI | /admin/ — browse history, edit agents live, watch the real-time task board. | | YAML-driven | Every setting lives in coulisse.yaml. coulisse schema emits a JSON Schema for IDE validation. |

Status: pre-1.0 — usable for prototypes and personal projects. Minor version bumps may include breaking changes until 1.0. See the [changelog](CHANGELOG.md) for what's shipped and the [roadmap](docs/src/reference/roadmap.md) for what's next.

Upgrading from v0.1.0

The memory: block was reshaped. The old fields backend, embedder, extractor, context_budget, memory_budget_fraction, and recall_k are gone. Replace the whole block with:

memory:
  storage: ./coulisse-memory.db
  user_state: true   # add this only if you had long-term memory enabled before

Run coulisse migrate (or just start — the migrator runs at boot). See the [memory configuration guide](docs/src/configuration/memory.md) for the full schema.

Documentation

The user guide lives in an mdbook under [docs/](docs/). Preview it locally:

mdbook serve docs --port 4421

Then open .

Contributing

The repo ships a pre-commit hook at .githooks/pre-commit that runs cargo fmt --check, cargo clippy, cargo sort-derives --check, cargo machete, and cargo test. Enable it once per clone:

git config core.hooksPath .githooks

Install the dev tools (cargo-watch, mdbook) with just install. The lint stack uses cargo fmt, cargo clippy, plus cargo-sort-derives and cargo-machete — install the latter two via cargo install cargo-sort-derives cargo-machete --locked if not already on your system.

License

MIT. See [LICENSE](LICENSE).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Almaju
• Source: Almaju/coulisse
• License: MIT
• Homepage: https://almaju.github.io/coulisse/

Install and usage instructions live in the source repository linked above.