> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crewship.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# crewship.toml

> Configure your crew deployment

## Overview

The `crewship.toml` file configures how your crew is built and deployed. Place it in your project root.

Crewship supports two formats:

* **Single deployment** — one `[deployment]` section (default, created by `crewship init`)
* **Multi-deployment** — multiple `[deployments.<name>]` sections for monorepos with several agents

<Tip>
  Run [`crewship init`](/cli/init) to auto-generate this file with detected settings from your project.
</Tip>

## Single Deployment (default)

<Tabs>
  <Tab title="CrewAI">
    ```toml crewship.toml theme={null}
    [deployment]
    framework = "crewai"
    entrypoint = "src.my_crew.crew:MyCrew"
    profile = "slim"
    python = "3.11"

    [build]
    exclude = ["tests"]
    ```
  </Tab>

  <Tab title="LangGraph">
    ```toml crewship.toml theme={null}
    [deployment]
    framework = "langgraph"
    entrypoint = "src.my_agent.graph:graph"
    profile = "slim"
    python = "3.11"

    [build]
    exclude = ["tests"]
    ```
  </Tab>

  <Tab title="LangGraph.js">
    ```toml crewship.toml theme={null}
    [deployment]
    framework = "langgraph-js"
    entrypoint = "./src/graph.ts:graph"
    profile = "slim"

    [build]
    exclude = ["tests"]
    ```
  </Tab>
</Tabs>

## Multi-Deployment

For monorepos with multiple agents sharing the same codebase, use named `[deployments.<name>]` sections:

```toml crewship.toml theme={null}
[build]
exclude = ["tests"]

[deployments.research-agent]
framework = "crewai"
entrypoint = "research_crew.crew:ResearchCrew"
profile = "slim"
python = "3.11"

[deployments.writer-agent]
framework = "crewai"
entrypoint = "writer_crew.crew:WriterCrew"
```

Each named deployment gets its own deployment on Crewship with the name as the project name (e.g. `research-agent`).

`[apis]` and `[chat]` can be set at the top level as global defaults, and overridden per deployment:

```toml crewship.toml theme={null}
# Global defaults
[chat]
input_key = "query"

[deployments.support-agent]
framework = "crewai"
entrypoint = "support_crew.crew:SupportCrew"

[deployments.research-agent]
framework = "crewai"
entrypoint = "research_crew.crew:ResearchCrew"

# Override chat config for this deployment only
[deployments.research-agent.chat]
input_key = "topic"
```

<Warning>
  `[deployment]` and `[deployments.*]` are mutually exclusive. Using both in the same file will produce an error.
</Warning>

### Selecting a deployment

Use `--name` / `-n` on any command to target a specific deployment:

```bash theme={null}
crewship deploy --name research-agent
crewship invoke --name writer-agent --input '{"topic": "AI"}'
crewship env set --name research-agent OPENAI_API_KEY=sk-...
```

If `--name` is omitted:

* **One named deployment** — auto-selected
* **Multiple named deployments** — interactive prompt (or error in CI)
* **Single `[deployment]` format** — used directly (no `--name` needed)

### Deployment IDs

After the first deploy, `deployment_id` is saved into each section automatically:

```toml theme={null}
[deployments.research-agent]
framework = "crewai"
entrypoint = "research_crew.crew:ResearchCrew"
deployment_id = "dep_xxx1"   # auto-populated

[deployments.writer-agent]
framework = "crewai"
entrypoint = "writer_crew.crew:WriterCrew"
deployment_id = "dep_xxx2"   # auto-populated
```

## Full Example

```toml crewship.toml theme={null}
[deployment]
framework = "crewai"
entrypoint = "src.research_crew.crew:ResearchCrew"
python = "3.11"
profile = "slim"

[build]
exclude = ["tests"]

[build.install]
packages = ["ffmpeg", "imagemagick"]

[apis]
enabled = ["thread", "run"]

[chat]
input_key = "topic"

[runtime]
timeout = 600
memory = 512

[metadata]
description = "A crew that researches topics and writes reports"
tags = ["research", "writing"]
```

## Configuration Reference

### \[deployment] / \[deployments.\<name>]

| Field           | Type   | Required | Description                                                      |
| --------------- | ------ | -------- | ---------------------------------------------------------------- |
| `framework`     | string | ✅        | Framework to use: `crewai`, `langgraph`, or `langgraph-js`       |
| `entrypoint`    | string | ✅        | Entry point for your agent (format varies by framework)          |
| `python`        | string | `"3.11"` | Python version (`3.10`, `3.11`, `3.12`) — Python frameworks only |
| `profile`       | string | `"slim"` | Base image profile                                               |
| `dockerfile`    | string | —        | Custom Dockerfile path                                           |
| `deployment_id` | string | —        | Auto-populated after first deploy                                |

#### Entrypoint Format

The entrypoint format depends on your framework:

**CrewAI and LangGraph (Python)** — Python module path:

```
module.path:ClassName_or_variable
```

```toml theme={null}
# CrewAI: points to a class decorated with @CrewBase
entrypoint = "src.my_crew.crew:MyCrew"

# LangGraph: points to a compiled graph variable
entrypoint = "src.my_agent.graph:graph"
```

**LangGraph.js** — file path relative to project root:

```
./path/to/file.ts:exportName
```

```toml theme={null}
# LangGraph.js: points to an exported compiled graph
entrypoint = "./src/graph.ts:graph"
```

<Tip>
  Run `crewship init` to auto-detect your framework and entrypoint. For LangGraph projects, place a `langgraph.json` in your project root to enable auto-detection.
</Tip>

#### Profile Options

| Profile   | Description                    | Frameworks            | Use case                  |
| --------- | ------------------------------ | --------------------- | ------------------------- |
| `slim`    | Minimal base environment       | All                   | Most agents               |
| `browser` | Includes Playwright + Chromium | `crewai`, `langgraph` | Web scraping, screenshots |

### \[build]

Build configuration options.

| Field     | Type            | Default | Description                 |
| --------- | --------------- | ------- | --------------------------- |
| `exclude` | array of string | `[]`    | Paths to exclude from build |

### \[build.install]

Additional system packages to install.

```toml theme={null}
[build.install]
packages = ["ffmpeg", "poppler-utils", "tesseract-ocr"]
```

<Note>Only packages available in the base image's package manager (apt) are supported.</Note>

### \[runtime]

Runtime configuration.

| Field     | Type    | Default | Description                   |
| --------- | ------- | ------- | ----------------------------- |
| `timeout` | integer | `300`   | Max execution time in seconds |
| `memory`  | integer | `256`   | Memory limit in MB            |

```toml theme={null}
[runtime]
timeout = 900    # 15 minutes
memory = 1024    # 1 GB
```

### \[apis]

Controls which APIs are enabled for the deployment. This affects both direct API access and which interaction modes are available in [Slack](/guides/slack).

| Field     | Type            | Default | Description                               |
| --------- | --------------- | ------- | ----------------------------------------- |
| `enabled` | array of string | —       | Which APIs to expose: `"thread"`, `"run"` |

When omitted (or `null`), **all APIs are enabled** by default.

```toml theme={null}
[apis]
enabled = ["thread", "run"]   # Both APIs enabled (same as default)
```

```toml theme={null}
[apis]
enabled = ["run"]   # Only stateless runs — no thread/conversation support
```

```toml theme={null}
[apis]
enabled = ["thread"]   # Only threaded conversations — no standalone runs
```

<Info>
  In Slack, the enabled APIs determine which interaction modes work:

  * **Thread API** — `@mention` conversations use threads for multi-turn context
  * **Run API** — `/crewship run` slash commands use single stateless runs
  * If both are enabled, `@mention` defaults to thread mode

  Not sure which to use? Read [Runs vs Threads: When to Use Which](https://www.crewship.dev/blog/runs-vs-threads-when-to-use-which).
</Info>

### \[chat]

Configures how chat messages (from Slack or other integrations) map to your crew's input and output.

| Field        | Type   | Default   | Description                                          |
| ------------ | ------ | --------- | ---------------------------------------------------- |
| `input_key`  | string | `"input"` | The parameter name that receives the chat message    |
| `output_key` | string | —         | Field in the run output containing response messages |

```toml theme={null}
[chat]
input_key = "topic"
```

When a user sends a message in Slack (e.g. "Tell me about quantum computing"), it gets mapped to:

```json theme={null}
{ "topic": "Tell me about quantum computing" }
```

If `output_key` is set, the platform extracts that field from the run result to display as the response:

```toml theme={null}
[chat]
input_key = "query"
output_key = "messages"
```

<Tip>
  If your crew already accepts an `input` parameter, you can omit `[chat]` entirely — it defaults to `input_key = "input"`.
</Tip>

### \[metadata]

Optional metadata for organization.

| Field         | Type   | Description                   |
| ------------- | ------ | ----------------------------- |
| `description` | string | Human-readable description    |
| `tags`        | array  | Tags for filtering in Console |

```toml theme={null}
[metadata]
description = "Researches topics and generates blog posts"
tags = ["content", "blog", "research"]
```

## Validation

The CLI validates your `crewship.toml` on deploy:

```bash theme={null}
crewship deploy
```

Common validation errors:

```
❌ Error: Invalid crewship.toml
   - name: must be lowercase with hyphens only
   - deployment.entrypoint: required field missing
```

## Environment-specific Config

For different environments, use separate projects:

```bash theme={null}
# Production
crewship deploy --project my-crew

# Staging
crewship deploy --project my-crew-staging
```

Set different environment variables per project:

```bash theme={null}
crewship env set OPENAI_API_KEY=sk-prod-... --project my-crew
crewship env set OPENAI_API_KEY=sk-test-... --project my-crew-staging
```

## Example Configurations

### Basic CrewAI

```toml theme={null}
[deployment]
framework = "crewai"
entrypoint = "src.simple_crew.crew:SimpleCrew"
```

### Basic LangGraph

```toml theme={null}
[deployment]
framework = "langgraph"
entrypoint = "src.my_agent.graph:graph"
python = "3.11"
```

### Basic LangGraph.js

```toml theme={null}
[deployment]
framework = "langgraph-js"
entrypoint = "./src/graph.ts:graph"
```

### Web Scraping Crew

```toml theme={null}
[deployment]
framework = "crewai"
entrypoint = "src.scraper.crew:ScraperCrew"
profile = "browser"
python = "3.11"

[runtime]
timeout = 600
memory = 1024
```

### Document Processing

```toml theme={null}
[deployment]
framework = "crewai"
entrypoint = "src.processor.crew:ProcessorCrew"
python = "3.11"

[build.install]
packages = ["poppler-utils", "tesseract-ocr"]

[runtime]
timeout = 900
memory = 2048
```

### Slack Chatbot

```toml theme={null}
[deployment]
framework = "crewai"
entrypoint = "src.support_bot.flows.chat_flow:ChatFlow"
python = "3.11"

[apis]
enabled = ["thread"]

[chat]
input_key = "query"
output_key = "messages"
```

### Multi-Agent Monorepo (mixed frameworks)

```toml theme={null}
[build]
exclude = ["tests", "notebooks"]

[deployments.research-agent]
framework = "crewai"
entrypoint = "agents.research.crew:ResearchCrew"
profile = "browser"
python = "3.11"

[deployments.writer-agent]
framework = "langgraph"
entrypoint = "agents.writer.graph:graph"
python = "3.11"

[deployments.frontend-agent]
framework = "langgraph-js"
entrypoint = "./agents/frontend/graph.ts:graph"
```

Deploy individual agents:

```bash theme={null}
crewship deploy --name research-agent
crewship deploy --name writer-agent
```

## Related

<CardGroup cols={2}>
  <Card title="Deploy" icon="rocket" href="/cli/deploy">
    Deploy your configured crew
  </Card>

  <Card title="Slack Integration" icon="slack" href="/guides/slack">
    Connect your crew to Slack
  </Card>

  <Card title="Environment Variables" icon="key" href="/configuration/environment-variables">
    Configure secrets
  </Card>

  <Card title="Threads" icon="comments" href="/guides/threads">
    Multi-turn conversations
  </Card>
</CardGroup>