Get started

Three parts. Only the first is required.

Everything runs in three containers on your machine: about a 1 GB download of prebuilt images, one command. Your assistant and the browser panel attach whenever you want them.

Apache-2.0

No account

≈1¢ per application

127.0.0.1 only

The shape of it

What a complete setup looks like

The app

required

git clone, then one docker compose up -d: about a 1 GB image download, three containers, all on localhost. Your API key goes in afterwards, inside the app: Settings → Models. OpenAI or Gemini, either alone is a complete setup.

Your assistant

optional

An MCP server, installed from your client's own settings: Claude takes an extension file from the cloned folder, Codex and the ChatGPT desktop app take a plugin marketplace. No terminal, no config file, no host Python.

The browser panel

optional

chrome://extensions → Developer mode → Load unpacked → the repo's extension/ folder. No ID to copy, nothing to configure.

Part 1 · required

Install the app

Three steps, in order. Before you start, you need exactly two tools and one download's worth of patience.

Docker Desktop

Or Docker Engine with Compose v2. Start it and leave it running.

Git

It's how you install, and later update. macOS offers to install it on first use; Windows takes Git for Windows.

About a 1 GB download

The three images, compressed. They unpack to roughly 3–4 GB; the backend is the big one, carrying a minimal TeX Live, Typst and the embedding model.

One API key, recommended

OpenAI or Gemini, added in Settings → Models after first boot. Without one you still get the deterministic core, and over MCP your assistant supplies the model.

Clone and start

Three commands. The images arrive prebuilt: about a 1 GB download, a few minutes on a normal connection.

bash

git clone https://github.com/seinun-ai/maestro-career-studio.git
cd maestro-career-studio
cp .env.example .env

# Downloads prebuilt images, about 1 GB. Your API key comes later,
# inside the app: Settings -> Models after first boot.

docker compose up -d

Open the app

http://localhost:3000. First boot runs migrations and seeds a demo resume with rendered previews; give it a moment.

Add your API key, inside the app

Settings → Models: paste one key, OpenAI or Gemini, and press Test on each model. A key saved in the app always wins over one in .env, so pick one place and stay there. Which key, and what it costs

Port already allocated?

All three host ports are overridable in .env: BACKEND_HOST_PORT (8001), FRONTEND_HOST_PORT (3000) and POSTGRES_HOST_PORT (55432). Only the host side of the mapping moves.

Let an agent install it

Already using Claude Code, the Codex CLI or Cursor? Open a session in the folder you want it in and paste this. It clones, configures and starts the stack for you.

paste into your agent

Clone https://github.com/seinun-ai/maestro-career-studio, check that the prerequisites in docs/GETTING_STARTED.md are present on this machine, set up the .env, and start the stack with docker compose. Then tell me what still needs me.

Two things an agent can't do for you

Install and start Docker Desktop (and Git). They need an admin password and a GUI first run.

Decide where your API key goes. That one is a judgement call, and it's yours.

If something goes wrong

You see	It means	Do
`Cannot connect to the Docker daemon`	Docker isn't running	Start Docker Desktop, wait for “running”, re-run the command
`port is already allocated`	Another app owns 3000, 8001 or 55432	Change the matching *_HOST_PORT in .env
`Build sits at TeX Live or the model download`	Normal on a first build	Wait it out. Later builds are fast.
`Page loads but everything errors`	Backend still starting	curl -s localhost:8001/health answers {"status":"ok"} when it's ready
`Added a key to .env after starting`	Keys are read at process start	docker compose restart backend. Remember that an in-app key overrides .env
`Calls fail 401 though Settings says Configured`	A stale key. The label says where it lives.	Re-enter it in Settings → Models and press Test

Part 2 · optional

Attach your assistant (MCP)

Two paths, both from the client's own settings. No terminal, no config file, no host Python: the server runs inside the backend container Part 1 started.

Claude

Claude Desktop, and Claude Code inside the Claude app. One install covers both

Settings → Extensions → Install Extension

Pick mcpb/maestro-career-studio.mcpb inside the folder Part 1 created

Leave the fields at their defaults and install

The Tool profile field stays full unless you later want a scoped set.

Codex / ChatGPT desktop

The ChatGPT desktop app and the Codex CLI share this install

Settings → Plugins → Add plugin marketplace

Source seinun-ai/maestro-career-studio · git ref main · sparse paths empty

Open the Maestro Career Studio entry and press Install

The plugin is pinned to the full profile; scoping it means the hand-written entry below.

Six profiles: full by default, scoped when you customize

Both installs load all 83 tools: the full profile, and the right default. The five scoped trims (hunt, apply, explore, templates, career) are a customization you add by editing the config directly: change MAESTRO_CS_MCP_PROFILE in the JSON or TOML below, or set the Claude extension's Tool profile field. One profile at a time.

If an install misbehaves, write the config by hand

Both apps read a plain config file, and a hand-written entry always works: if it connects, the server is fine and the packaging was the problem. Both entries run the server inside the backend container, so neither needs a host Python.

Claude Desktop · claude_desktop_config.json

add under mcpServers

"maestro-career-studio": {
  "command": "docker",
  "args": ["exec", "-i",
           "-e", "BACKEND_URL=http://localhost:8000",
           "-e", "MAESTRO_CS_MCP_PROFILE=full",
           "maestro-career-studio-backend-1",
           "python", "-m", "mcp_server.server"]
}

Fully quit Claude first (Cmd+Q; closing the window is not enough): the running app rewrites this file on exit and silently drops your edit. Reach it via Settings → Developer → Edit Config, add the entry under mcpServers, save, reopen.

Codex / ChatGPT desktop · ~/.codex/config.toml

append to the file

[mcp_servers.maestro-career-studio]
command = "docker"
args = ["exec", "-i",
        "-e", "BACKEND_URL=http://localhost:8000",
        "-e", "MAESTRO_CS_MCP_PROFILE=full",
        "maestro-career-studio-backend-1",
        "python", "-m", "mcp_server.server"]
enabled = true

Append the block, then restart the app. The file is shared by the ChatGPT desktop app and the Codex CLI; Codex also takes the same command through Settings → MCPs → Connect a custom MCP, type STDIO.

Cursor, Windsurf, another stdio client, or a backend outside Docker? ./scripts/setup-mcp.sh prints a paste-ready block per client, the one route that needs a host Python 3.12+. What agents can do with it

Part 3 · optional

The browser panel

A Chrome side panel: capture the posting in front of you and fill forms from your autofill profile. Unrelated to Part 2, despite the shared word “extension”.

Open chrome://extensions and turn on Developer mode

Load unpacked → the repo's extension/ folder

Pin the icon, then click it on any job page

No ID to copy, nothing to configure. The extension pins its identity, so the backend already allowlists it out of the box. If you changed the ports in .env, set the backend and app URLs under the panel's ⋯ menu.

Stay current

Updating is one command

Run it from the folder you cloned. It backs up the database, moves your checkout to the newest release, brings the images to that same version, and waits until the stack is healthy again.

bash

./scripts/update.sh

--check changes nothing and answers only: am I up to date? On Windows, run it under WSL.

Your data is not involved

Resumes, applications, KB documents and settings are files on disk no update step touches, and the database lives in a Docker volume that survives all of this. The backup guards the migration specifically.

Migrations run themselves

They run when the backend starts, so the first boot after an update takes longer than usual. The script tells you it's waiting.

Two things stay manual

Docker can't reach them: reload the extension at chrome://extensions and reload any open job tab, then restart your MCP client. The script prints both reminders when it finishes.

Then what?

The guide walks you through the first hour.

This page installs it. The guide is the using: your first session in the order that works, the browser panel in action, and what to ask your assistant for.

Your first session, in order

Eleven steps from importing resumes to tracking the application. The order is the point.

Driving it from your assistant

What to ask for over MCP, and the panel's Job → Score → Resume → Fill → Track ladder.

Open the guide