Core Concepts

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

# Input is passed as the initial graph state
graph.invoke({"topic": "quantum computing", "style": "blog"})

// Input is passed as the initial graph state
await graph.invoke({ topic: "quantum computing", style: "blog" })

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

# Get artifact download URL
curl https://api.crewship.dev/v1/runs/run_xyz789/artifacts/report.md \
  -H "Authorization: Bearer YOUR_API_KEY"

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"

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.

Getting Started

CLI Reference

Configuration

Guides

Overview

Deployments

What’s in a deployment?

Rollbacks

Runs

Run isolation

Run inputs

Artifacts

How artifacts work

Accessing artifacts

Common artifact types

Events

Event types

Streaming events

Environment Variables

Next Steps

CLI Reference

Configuration

​Overview

​Deployments

​What’s in a deployment?

​Rollbacks

​Runs

​Run isolation

​Run inputs

​Artifacts

​How artifacts work

​Accessing artifacts

​Common artifact types

​Events

​Event types

​Streaming events

​Environment Variables

​Next Steps

CLI Reference

Configuration

Overview

Deployments

What’s in a deployment?

Rollbacks

Runs

Run isolation

Run inputs

Artifacts

How artifacts work

Accessing artifacts

Common artifact types

Events

Event types

Streaming events

Environment Variables

Next Steps