Installation (Local Development)

This guide is for developers who want to run AgentShip locally without Docker.

💡 New to AgentShip? Start with Docker Setup - it’s much easier!

Prerequisites

  • Python 3.13+

  • pipenv (recommended) or pip

  • PostgreSQL (optional, for persistent sessions)

  • At least one LLM API key (OpenAI, Google, or Anthropic)

Quick Setup

Manual Setup

If you prefer manual setup:

# 1. Clone and navigate
git clone https://github.com/Agent-Ship/agent-ship.git
cd agent-ship

# 2. Install dependencies
pipenv install --dev

# 3. Configure environment
cp env.example .env
# Edit .env and add your API keys (at least one LLM provider)

Configure Environment

Edit .env with your API keys:

# Required: At least one LLM provider
OPENAI_API_KEY=your_openai_api_key
GOOGLE_API_KEY=your_google_api_key
ANTHROPIC_API_KEY=your_anthropic_api_key

# Optional: Database for persistent session management
AGENT_SESSION_STORE_URI=postgresql://user:password@host:port/database

# Optional: Observability
OPIK_API_KEY=your_opik_api_key
OPIK_WORKSPACE=your_workspace

See Configuration Guide for all environment variables.

Set Up Database (Optional)

For persistent session storage, set up PostgreSQL:

Using Setup Script

cd agent_store_deploy
./setup_local_postgres.sh
cd ..

Manual Setup

# Install PostgreSQL (macOS)
brew install postgresql
brew services start postgresql

# Create database and user
createdb ai_agents_session_store
psql ai_agents_session_store -c "CREATE USER ai_agents_user WITH PASSWORD 'ai_agents_password';"
psql ai_agents_session_store -c "GRANT ALL PRIVILEGES ON DATABASE ai_agents_session_store TO ai_agents_user;"

For production deployment, see the Deployment Guide.

Verify Installation

Start the service:

make dev
# or: pipenv run uvicorn src.service.main:app --reload --port 7001

Access the API documentation:

  • Swagger UI: http://localhost:7001/swagger

  • ReDoc: http://localhost:7001/redoc

  • Health Check: http://localhost:7001/health

Development Commands

make help          # Show all available commands
make dev           # Start development server
make test          # Run tests
make test-cov      # Run tests with coverage
make lint          # Run linters
make format        # Format code
make type-check    # Run type checking

Troubleshooting

Port Already in Use

# Kill process using port 7001
lsof -ti:7001 | xargs kill -9

Database Connection Failed

  • Check if PostgreSQL is running: brew services list | grep postgresql

  • Verify connection string in .env

  • Check database exists: psql -l | grep ai_agents_session_store

Import Errors

# Ensure you're in the virtual environment
pipenv shell

# Reinstall dependencies
pipenv install --dev

API Key Issues

  • Verify at least one API key is set in .env

  • Check key is valid and has sufficient credits

  • Test with a simple curl request

Session Storage

In-Memory Sessions (Default)

  • Sessions stored in memory

  • Lost when service restarts

  • Good for development and testing

Database Sessions (Optional)

  • Sessions persisted to PostgreSQL

  • Survive service restarts

  • Set AGENT_SESSION_STORE_URI in .env

Next Steps