> ## 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 deploy

> Deploy your crew to Crewship

## Usage

```bash theme={null}
crewship deploy [path] [options]
```

## Description

Packages your crew and deploys it to Crewship, or builds a local Docker image for testing.

**Remote deploy** (default):

1. **Packages** your project into a tarball
2. **Initializes** a deployment (or uses existing one based on project name)
3. **Creates** a new version
4. **Uploads** the build context to Crewship

**Local deploy** (`--local`):

1. **Builds** a Docker image locally using the base Crewship image
2. Optionally **runs** the container

## Options

| Option          | Description                                       |
| --------------- | ------------------------------------------------- |
| `[path]`        | Project directory (defaults to current directory) |
| `--name`, `-n`  | Deployment name (for multi-deployment configs)    |
| `--local`, `-l` | Build Docker image locally instead of deploying   |
| `--run`, `-r`   | Run the container after building (with `--local`) |
| `--port`, `-p`  | Port to expose when running (default: 8000)       |

## Examples

### Deploy to Crewship

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

### Deploy a specific directory

```bash theme={null}
crewship deploy ./my-crew
```

### Build and test locally

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

### Build and run locally

```bash theme={null}
crewship deploy --local --run
```

### Run on a custom port

```bash theme={null}
crewship deploy --local --run --port 9000
```

### Deploy a named deployment (multi-deployment)

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

If your `crewship.toml` has multiple `[deployments.<name>]` sections and you omit `--name`, the CLI prompts you to select one interactively.

## Output

### Remote Deploy

A successful remote deployment shows:

```
🚀 Deploying crew "my-crew" to Crewship

📡 Fetching organizations...
   Using organization: My Org (my-org)

📝 Initializing deployment...
   Created new deployment: dep_abc123xyz
   Saved deployment ID to crewship.toml

📝 Creating new version...
   Version: 1 (ver_xyz789)

📦 Packaging project...
   Package size: 0.12 MB

⬆️  Uploading context...
   Status: pending

✅ Deployed version 1 for "my-crew"!

   Deployment ID: dep_abc123xyz
   Version: 1
   Status: pending

   View in console: https://console.crewship.dev/deployments/dep_abc123xyz
```

### Local Deploy

A successful local build shows:

```
🚀 Deploying crew locally from /path/to/my-crew

  Framework:   crewai
  Entrypoint:  src.my_crew.main:kickoff
  Profile:     slim
  Image:       crewship-my-crew:latest

📦 Reading .env file...
   Found 3 environment variables

🔨 Building image...

✓ Image built: crewship-my-crew:latest

To run the crew locally:
  docker run -p 8000:8000 crewship-my-crew:latest

Or use:
  crewship deploy --local --run
```

## Requirements

Your project must have:

* `crewship.toml` in the project root with a `[deployment]` or `[deployments.<name>]` section
* A valid `entrypoint` pointing to your crew's kickoff function
* `pyproject.toml` for dependencies (installed via `uv pip install -e .`)

### Single deployment

```toml crewship.toml theme={null}
[deployment]
framework = "crewai"
entrypoint = "src.my_crew.main:kickoff"
```

### Multiple deployments

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

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

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

See the [crewship.toml reference](/configuration/crewship-toml) for details.

## Build Process

For local builds, Crewship generates a Dockerfile based on your configuration:

```dockerfile theme={null}
FROM crewship/crewai:py311-slim

# Copy project files
COPY . /app/project/

# Install dependencies
WORKDIR /app/project
RUN uv pip install -e .

WORKDIR /app

# Configure entrypoint
ENV CREWSHIP_ENTRYPOINT=src.my_crew.main:kickoff
```

<Info>
  You don't need to write a Dockerfile. Crewship generates one based on your `crewship.toml`.
</Info>

## Excluding Files

By default, the following files and directories are excluded from the build:

* `.git`, `.gitignore`
* `.env`, `.env.*`
* `.venv`, `venv`
* `__pycache__`, `*.pyc`, `*.pyo`
* `.pytest_cache`, `.mypy_cache`, `.ruff_cache`
* `node_modules`
* `.DS_Store`, `Thumbs.db`
* `*.egg-info`, `dist`, `build`
* `.idea`, `.vscode`
* `*.log`
* `Dockerfile`, `.dockerignore`

To exclude additional files, add them to your `crewship.toml`:

```toml crewship.toml theme={null}
[deployment]
framework = "crewai"
entrypoint = "src.my_crew.main:kickoff"

[build]
exclude = [
  "tests/",
  "data/*.csv",
  "*.md",
]
```

## Troubleshooting

### "crewship.toml not found"

Make sure you're in the project root directory and have a `crewship.toml` file. Run `crewship init` to create one.

### "Not logged in"

Run `crewship login` to authenticate before deploying to Crewship.

### "Missing deployment.framework" or "Missing deployment.entrypoint"

Your `crewship.toml` must have a `[deployment]` or `[deployments.<name>]` section with both `framework` and `entrypoint`:

```toml theme={null}
[deployment]
framework = "crewai"
entrypoint = "src.my_crew.main:kickoff"
```

### "No organizations found"

Create an organization in the [Console](https://console.crewship.dev) before deploying.

### "Session expired"

Your login session has expired. Run `crewship login` again.

### Local build: "Base image not found"

For local builds, the CLI will attempt to build the base image automatically. If this fails, ensure Docker is running and you have access to the `packages/runner-crewai` directory.

## Related

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/configuration/crewship-toml">
    Configure your deployment
  </Card>

  <Card title="Environment Variables" icon="key" href="/configuration/environment-variables">
    Set secrets before deploying
  </Card>
</CardGroup>