Overview
Crewship uses a simple but powerful execution model. Understanding these core concepts will help you get the most out of the platform.
Projects
A project is a container for your crew deployments. Each project:
- Has a unique name (e.g.,
research-crew)
- Contains multiple deployments
- Holds environment variables
- Tracks usage and billing
Project: research-crew
├── Deployment: dep_abc123 (current)
├── Deployment: dep_xyz789 (previous)
├── Environment Variables
└── Settings
Deployments
A deployment is an immutable snapshot of your crew at a point in time.
Think of deployments like Git commits — each one captures a specific version of your code.
What’s in a deployment?
- Your crew source code
- Python dependencies (from
requirements.txt or pyproject.toml)
- Crewship configuration (
crewship.toml)
- A container image built from the above
Rollbacks
Since deployments are immutable, rolling back is instant:
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
Pass data to your crew via the input parameter:
crewship invoke --input '{"topic": "quantum computing", "style": "blog"}'
def kickoff(inputs: dict):
topic = inputs.get("topic")
style = inputs.get("style")
# ...
Artifacts
Artifacts are files produced by your crew during a run.
How artifacts work
- Your crew writes files to
/app/artifacts/
- When the run completes, Crewship collects these files
- Artifacts are stored durably and accessible via API
# In your crew
with open("/app/artifacts/report.md", "w") as f:
f.write(generated_report)
Accessing artifacts
# List artifacts
crewship runs artifacts run_xyz789
# Download an artifact
crewship runs download run_xyz789 report.md
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:
curl -N https://api.crewship.dev/v1/runs/run_xyz789/events \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: text/event-stream"
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:
# 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"]
Never commit API keys or secrets to your repository. Use environment variables instead.
Next Steps
