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

# Core Concepts

> Understanding deployments, runs, artifacts, and the Crewship execution model

## Overview

Crewship uses a simple but powerful execution model. Understanding these core concepts will help you get the most out of the platform.

## Deployments

A **deployment** is an immutable snapshot of your crew at a point in time.

<Info>
  Think of deployments like Git commits — each one captures a specific version of your code.
</Info>

### What's in a deployment?

* Your agent source code
* Dependencies (Python: `requirements.txt` / `pyproject.toml`; JavaScript: `package.json`)
* Crewship configuration (`crewship.toml`)
* A container image built from the above

### Rollbacks

Since deployments are immutable, rolling back is instant:

```bash theme={null}
crewship deploy --rollback dep_xyz789
```

## Runs

A **run** is a single execution of your crew.

### Run isolation

Each run:

* Gets its own container instance
* Has no shared state with other runs
* Is completely isolated
* Scales to zero when complete

### Run inputs

Pass data to your agent via the `input` parameter:

```bash theme={null}
crewship invoke --input '{"topic": "quantum computing", "style": "blog"}'
```

Crewship passes this JSON object to your agent. How it's received depends on your framework:

<CodeGroup>
  ```python CrewAI theme={null}
  def kickoff(inputs: dict):
      topic = inputs.get("topic")
      style = inputs.get("style")
      # ...
  ```

  ```python LangGraph theme={null}
  # Input is passed as the initial graph state
  graph.invoke({"topic": "quantum computing", "style": "blog"})
  ```

  ```typescript LangGraph.js theme={null}
  // Input is passed as the initial graph state
  await graph.invoke({ topic: "quantum computing", style: "blog" })
  ```
</CodeGroup>

## Artifacts

**Artifacts** are files produced by your crew during a run.

### How artifacts work

1. Your crew writes files to `/app/artifacts/`
2. When the run completes, Crewship collects these files
3. Artifacts are stored durably and accessible via API

```python theme={null}
# In your crew
with open("/app/artifacts/report.md", "w") as f:
    f.write(generated_report)
```

### Accessing artifacts

<CodeGroup>
  ```bash CLI theme={null}
  # List artifacts
  crewship runs artifacts run_xyz789

  # Download an artifact
  crewship runs download run_xyz789 report.md
  ```

  ```bash cURL theme={null}
  # Get artifact download URL
  curl https://api.crewship.dev/v1/runs/run_xyz789/artifacts/report.md \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

### Common artifact types

| Type      | Extension       | Use case                     |
| --------- | --------------- | ---------------------------- |
| Reports   | `.md`, `.txt`   | Generated content, summaries |
| Data      | `.json`, `.csv` | Structured output, datasets  |
| Documents | `.pdf`, `.docx` | Formatted documents          |
| Images    | `.png`, `.jpg`  | Generated visualizations     |

## Events

**Events** are structured messages emitted during a run. They enable real-time streaming and observability.

### Event types

| Event             | Description               |
| ----------------- | ------------------------- |
| `run.started`     | Run execution began       |
| `run.completed`   | Run finished successfully |
| `run.failed`      | Run encountered an error  |
| `log`             | Log message from the crew |
| `artifact`        | Artifact was produced     |
| `agent.started`   | Agent began a task        |
| `agent.completed` | Agent finished a task     |
| `tool.called`     | Tool was invoked          |

### Streaming events

Connect to the event stream via SSE:

```bash theme={null}
curl -N https://api.crewship.dev/v1/runs/run_xyz789/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: text/event-stream"
```

Events arrive as they happen:

```
event: log
data: {"message": "Researcher agent starting..."}

event: agent.started
data: {"agent": "Researcher", "task": "Research topic"}

event: artifact
data: {"name": "notes.md", "size": 1234}

event: run.completed
data: {"duration_ms": 45200}
```

## Environment Variables

Store secrets and configuration outside your code:

```bash theme={null}
# Set a variable
crewship env set OPENAI_API_KEY=sk-...

# Variables are available in your crew
import os
api_key = os.environ["OPENAI_API_KEY"]
```

<Warning>
  Never commit API keys or secrets to your repository. Use environment variables instead.
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="CLI Reference" icon="terminal" href="/cli/overview">
    Master the Crewship CLI
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration/crewship-toml">
    Customize your deployments
  </Card>
</CardGroup>