Overview

A workbench can run backing services - databases, caches, object storage, queues - next to your code. Curated services come fully wired with sensible dev defaults, a readiness healthcheck, and a connection env injected into the workspace; any other Docker image works too. This page covers the shared model; each curated service has its own page with details.

New to Monoceros? Start with Installation.

Curated services

Add a curated service by name, at init or later:

monoceros init acme --with-services=postgres
monoceros add-service acme redis

Note

acme is just a sample workbench name - it’s whatever you passed to monoceros init. Substitute your own throughout.

The curated set:

Service	For
PostgreSQL	relational database
pgvector	Postgres + vector search (embeddings)
MySQL	relational database
MongoDB	document database
Redis	in-memory key-value store / cache
RustFS	S3-compatible object storage
Mailpit	local SMTP catcher with web inbox
Keycloak	identity & access management (OAuth2 / OIDC / SAML)
Caddy	reverse proxy: app and services under one address

The workspace waits for service_healthy (not just started), so your code only runs once the service is actually ready.

Connection env in the workspace

Each curated service injects a connection env into the workspace container, prefixed with the service name uppercased - e.g. a postgres service gives POSTGRES_URL, POSTGRES_HOST, POSTGRES_PORT, … The app/agent reads those instead of hardcoding anything. Monoceros does not inject a bare DATABASE_URL (that’s a project/framework concern); map <NAME>_URL in your project’s own .env if a tool expects a specific name.

Note

The container explains itself: apply writes an AGENTS.md / CLAUDE.md briefing at the workspace root that tells the agent which services are present and how to reach them (the <NAME>_* connection env), so it wires the app up without per-session setup.

More than one of the same engine

Service names are unique, and the connection-env prefix derives from the name - so you can run two of the same engine without collision. Add the second under a different name with --as:

monoceros init acme --with-services=postgres
monoceros add-service acme postgres --as=analytics

That yields POSTGRES_URL and ANALYTICS_URL, each pointing at its own instance with its own data dir.

Custom services

Any image works as a service, not only the curated ones: give a name and the image, and Monoceros scaffolds the block.

Talking to a service that already exists elsewhere (a managed database, say)? Don’t add a service at all - put its connection string in your project’s own .env, the same place your framework reads it.

Credentials and data

Service credentials are ${VAR} references in the yml; the real values live in acme.env, with dev defaults seeded for you (see Workbench configuration).

Tip

Service data lives in a Docker volume per service, monoceros-acme-data-<service>. The engine owns those files, which is what keeps a database from tripping over host file ownership on first start. The volume survives monoceros apply, and monoceros remove copies it into the backup as a plain directory, so a monoceros restore brings the data back.

To look at the live files, mount the volume into a throwaway container:

docker run --rm -v monoceros-acme-data-postgres:/data alpine ls -la /data

For a copy you want to keep, take the backup that monoceros remove writes instead of reaching into the volume.

Reaching a service from the host

A database port is TCP, so the HTTP proxy does not apply. Open a tunnel:

monoceros tunnel acme postgres

See Proxy and tunnels.

A service with a web interface has two more ways out, both from the same line in the yml: an httpPort. On the host the proxy gives it a permanent address, acme-<service>.localhost, with no command to keep running. From another device on your network, monoceros share serves it over HTTPS alongside the app. Keycloak declares 8080, the Mailpit inbox 8025, the RustFS console 9001. Databases have no httpPort and stay inside.