Skip to main content

​
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.
Think of deployments like Git commits — each one captures a specific version of your code.

​
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: 
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: 
crewship invoke --input '{"topic": "quantum computing", "style": "blog"}'
Crewship passes this JSON object to your agent. How it’s received depends on your framework: 
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

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

TypeExtensionUse case
Reports.md, .txtGenerated content, summaries
Data.json, .csvStructured output, datasets
Documents.pdf, .docxFormatted documents
Images.png, .jpgGenerated visualizations

​
Events

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

​
Event types

EventDescription
run.startedRun execution began
run.completedRun finished successfully
run.failedRun encountered an error
logLog message from the crew
artifactArtifact was produced
agent.startedAgent began a task
agent.completedAgent finished a task
tool.calledTool 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"
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: 
# 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

CLI Reference

Master the Crewship CLI

Configuration

Customize your deployments