Welcome to Cortex Setup Studio
A guided setup for your Cortex agent. Choose whether you're creating a new agent or updating an existing one.
What would you like to do?
✨
Create a new agent
Start fresh. Pick a quick-start preset or configure every step from scratch.
✏️
Update existing agent
Load your
cortex.yaml and edit it. All current settings are pre-filled; locked fields are protected.
Config imported successfully.
Your existing
cortex.yaml has been loaded. Proceed through the steps to review and edit any settings. Fields marked 🔒 cannot be changed safely after first setup.
No
cortex.yaml found at Quick-start presets (optional — you can skip and configure manually)
Each preset fills in agent identity, picks an LLM, and adds the most common tool servers — you can still tweak everything before saving.
What you'll configure
Agent identity → LLM provider → Tool servers (MCP) → Task types → Storage → Adaptive behavior → Runtime → Publish mode → Review.
Agent identity → LLM provider → Tool servers (MCP) → Task types → Storage → Adaptive behavior → Runtime → Publish mode → Review.
Before you start — make sure your LLM provider's API key is set as an environment variable (e.g.
ANTHROPIC_API_KEY). Setup Studio never stores keys, only the env-var name.
Agent identity
Give your agent a name and describe what it does. The description steers how the LLM decomposes user requests.
Identity
Agent name*
A short, descriptive name. Used as the session identity and referenced in logs.
🔒 Locked — changing this can break existing sessions.
Description*
Used by the LLM to understand the agent's purpose and decompose user requests.
Interaction mode*
Interactive — chat UIs, human users; intent gate routes each turn as chat or task.
RPC / API — headless callers, MCP servers; every message is treated as a task. Clarification is disabled.
RPC / API — headless callers, MCP servers; every message is treated as a task. Clarification is disabled.
💬
Interactive
Chat UI / human users
⚡
RPC / API
MCP server / API callers
Advanced — synthesis guidance, performance, streaming, clarification
Synthesis
Free-form instructions injected into the final answer composition. Steer tone, formatting, or citation style.
Performance
Start executing tasks as soon as the LLM emits them, instead of waiting for the entire plan.
Concurrency
Ceiling on LLM calls a single MCP sub-agent may make per request.
Streaming events (SSE)
Live progress over SSE so clients can render a progress UI.
Attach task name + summary to each event.
Re-emit progress events from nested MCP agents.
Past SSE events kept for reconnecting clients to replay.
Throttle: don't flush more than one event per this many ms.
Clarification
Let the agent pause and ask the user when a request is ambiguous.
LLM provider
Choose the language model that powers your agent's reasoning.
Default provider
Provider*
Model*
Any tag you've pulled locally — e.g.
gemma4:e4b.Base URL
The env var name where your API key is stored (e.g.
ANTHROPIC_API_KEY). Don't paste the key itself.Max tokens
Upper bound on completion tokens per call.
Temperature
Lower = more deterministic.
Gemma 4 quick-start (Ollama) — Run Google's Gemma 4 locally; Apache 2.0; no API keys.
- Install Ollama from ollama.com/download
ollama pull gemma4:e4b(sweet spot, ~3 GB)- Leave Base URL as
http://localhost:11434/v1
http://localhost:1234/v1) and vLLM (http://localhost:8000/v1) too.
Advanced — headers, Bedrock/Azure credentials, additional named providers
Custom headers
Added to every LLM request. Useful for proxy gateways requiring routing headers.
AWS Bedrock
Azure AI
Additional named providers
Define extra providers that task types can target via
llm_provider:. Mix cheap/fast models with the default.Adaptive Model Routing (AMR)
Decomposer assesses each task's complexity (low / medium / high) and routes it to the matching provider. Explicit
llm_provider on a task type always wins.Map each complexity tier to a provider. The decomposer grades tasks objectively — no provider bias in the assessment.
Simple retrieval, formatting, short text.
Multi-step reasoning, moderate code, single-doc analysis.
Complex architecture, multi-file codegen, deep synthesis.
Provider for wave-level task validation. Leave blank to auto-select the first non-default provider.
Tool servers (MCP)
Connect external tools via the Model Context Protocol. Browse the marketplace below or add a custom server.
Browse MCP Marketplace
→
No tool servers yet. Pick from the marketplace above, or add a custom one below.
Key used in cortex.yaml under
tool_servers. Must be unique — letters, numbers, underscores only.
SSE
Streamable HTTP
Stdio
Executable that speaks MCP over stdio.
CLI arguments passed to the command.
Full URL of the MCP endpoint.
Advanced — auth, connection, TLS, env, health check, discovery
Process env for stdio servers; passed at spawn.
Extra HTTP headers for SSE/HTTP servers.
Auth
Env var holding the bearer token.
Connection
TLS
Required for
https:// URLs; enable for custom CA / mTLS.Disable only for self-signed dev servers.
Connection pool
Discovery
Probe the server's tool list at startup.
Health check
Periodic ping; failed servers are isolated until recovery.
Task types
Define the kinds of tasks your agent can handle. Optional — the agent can auto-discover from its tools.
Each task type maps to a capability (LLM synthesis, web search, bash, sandboxed code, image/audio generation) and produces output in a chosen format.
No task types defined. Add one below, or skip — the agent decomposes tasks dynamically.
Filename or registry key for the lessons-learned blueprint.
Advanced — timeout, retries, tool servers, validation, schema
Required step in the agent's plan, even if the LLM doesn't pick it.
Task may pause and ask the user mid-run.
Schema used by the wave-gate judge.
Storage & persistence
Where the agent keeps state — session data, uploaded files, and disk quotas.
Backend
Storage backend
Memory: fastest, lost on restart. SQLite: persistent on disk. Redis: distributed.
🔒 Locked — existing data would be lost.
Storage path
Local directory for session data, uploaded files, blueprints.
SQLite path
Redis host
Redis port
Advanced storage settings — quotas, thresholds, TTLs, TLS
Quotas & thresholds
SQLite
Better concurrency.
Redis
File input
Adaptive behavior
Capability scout, learning, validation, blueprints, ant colony — the systems that let the agent improve over time.
Web search
Fall back to built-in DuckDuckGo search when no external web_search tool server is configured or reachable. Disable to block all automatic web searches.
Capability scout
Pre-probe MCP servers to map capabilities; steers decomposition.
External discovery
Scout looks up MCPs in public registries when capability is missing.
Validation (wave gates)
An LLM judge scores task outputs; failed tasks can retry or fail-fast.
Passes to fix a sub-threshold response — each sees the prior attempt and the findings it still failed. 1 = single-shot (legacy).
Weights sum:
— must equal 1.00
✓
Session history
Persist past sessions for cross-session memory and search.
Autonomic learning
Signal-gated lesson capture; no consent prompts.
💡 Blueprints auto-enabled — lessons captured by learning will be applied to task blueprints automatically.
Apply approved lessons to blueprints automatically.
Blueprints
Markdown lessons-learned files per task type.
Apply lessons to blueprints automatically.
Ant colony (specialist mesh)
Self-spawning specialist sub-agents.
Model and API key are inherited from the selected provider (configured in Step 2).
Let the agent generate and register new MCP servers from code during a session. Requires both ant colony and code sandbox.
When on, generated servers survive framework restart (auto_restart in ants.yaml).
Seconds to wait for the generated server to pass health-check.
Provider used to generate MCP server code. May warrant a stronger model.
Code sandbox
Run agent-authored code in an isolated subprocess.
Successful sandbox scripts get registered as task tools.
Workspace Bash
Let the agent read, write, and run commands in a user-specified local directory. Every write and command requires explicit user approval (HITL) — this cannot be disabled.
Use
workspace_bash as capability_hint on task types that need to read, write, or execute files in the user's project folder.
The workspace path is extracted from the task instruction — your UI should inject it into every message (e.g. "Workspace: /Users/me/project\n\n<user request>").
App Control
Launch and drive desktop applications via AppleScript (macOS), PowerShell + UI Automation (Windows), or a screenshot vision loop. Every mutating action requires user approval (HITL) unless you disable it below.
Prompt the user before each launch / script / screenshot. Disable only in trusted automation contexts.
Subprocess timeout for AppleScript / PowerShell / shell calls.
Cap on screenshot → action iterations when no scripting dictionary is found.
Trim long sdef / UIA summaries before injecting into LLM context.
LLM provider to use for vision steps. "default" = primary provider.
Playwright Browser (built-in)
Start
@playwright/mcp as an internal stdio MCP. The agent gets a browser capability automatically — no tool_server entry needed. Requires Node.js + npx on PATH.Hide the browser window (CI / server mode). Off = visible.
JSON file that persists cookies + localStorage across runs so logins survive. Leave blank for the auto default.
Full persistent browser profile (extensions, service workers, IndexedDB). Wins over storage_state_path when set.
Runtime & delivery
Concurrency limits, timeouts, chat UI, security, and startup behavior.
Time & concurrency
Maximum total wait for a single request.
Chat UI
Bundled web frontend for chat-style interaction.
Security
Anything matching these patterns is redacted from logs and stored data.
Startup
Fail boot if any tool server is unreachable.
Probe all servers at startup instead of lazily.
Per-user MCPs
Publish mode
How you want to deploy your agent. You can change this later, or skip to just save the YAML.
Docker
Containerized deploy. Builds
Dockerfile.cortex.Package
Builds a Python wheel for pip / PyPI.
MCP server
Expose this agent as an MCP server.
Chat UI
Web chat frontend backed by this agent.
Docker mode generates a
Dockerfile.cortex. Build with docker build -f Dockerfile.cortex . and run anywhere a container runs.Package mode builds a
.whl you can publish to PyPI or an internal registry. Users install with pip install.MCP server mode exposes capabilities as MCP tools so other agents can call them.
Chat UI mode serves a clean web chat frontend with file uploads, streaming, and per-user history.
⚡ MCP mode works best with RPC/API interaction. Go back to Step 1 and switch Interaction mode to RPC/API — it disables unnecessary clarification prompts that stall automated callers.
Image tag
Output directory
MCP server port
Chat UI publish target needs UI enabled in step 7 (Runtime). It'll be auto-enabled when you proceed.
After publishing — what to do next
🐳 Docker deployment guide
- Save config first — click Save cortex.yaml in the next step. The Dockerfile is generated alongside it.
- Build the image
- Pass your API key at runtime — never bake secrets into the image:
- Access the agent
- REST API →
POST http://localhost:8000/runwith JSON body{"input": "your request"} - Streaming SSE →
GET http://localhost:8000/run/stream?input=... - Chat UI →
http://localhost:8000/ui
- REST API →
- Persist storage — mount a volume so sessions survive container restarts:
docker run ... -v $(pwd)/data:/app/data ...
- Push to a registry (optional):
📦 Python package deployment guide
- Locate the wheel — after publishing, find
.whlin the output directory: - Install on the target machine:
- Set your API key env var:
- Run the agent:
- Access the agent at
http://localhost:8000/run - Publish to PyPI (optional):
🔌 MCP server deployment guide
- Start the MCP server: The MCP endpoint will be available at:
- Add this agent to another agent's
cortex.yaml: - Connect from Claude Desktop or any MCP client: add the server URL
in your client's MCP server list. - Verify tools are exposed:
- Keep the server running — use
screen,tmux, or asystemdservice in production.
💬 Chat UI deployment guide
- Start the agent server:
- Open the Chat UI in your browser:
-
Authentication — mode is set to
. The token you configured is passed viaAuthorization: Bearer <token>in API calls or?token=<token>in the browser. - Sending messages via REST (headless):
- Expose to your team — to allow inbound connections change the host to
0.0.0.0in Step 7 (Runtime) and put it behind an HTTPS proxy (nginx, Caddy, Cloudflare Tunnel). - Keep the server running — use
screen,tmux, or deploy via Docker (switch to Docker mode) for production.
Review & finish
Final config. Save it as
Config health score
/ 100
Generated YAML
Generating…
Save
Save path
Relative to the directory the wizard was launched from.
Recommendations
Publish output
✅ Published — here's how to access your agent
1 · Build the Docker image
2 · Run the container
3 · Access the agent
- Chat UI:
- MCP / REST:
1 · Install the wheel
2 · Set your API key
3 · Start the agent
4 · Open in your browser
1 · Start the MCP server
2 · MCP endpoint
3 · Add to another agent's cortex.yaml
1 · Set your API key & start
2 · Open in your browser
3 · Auth
Append ?token=<your_token> to the URL, or set Authorization: Bearer <token> in REST calls.