Features

• Local Inventory Tracking: SQLite database stores droplet metadata, snapshots, and reserved IPs locally for offline access and faster operations.

• Smart Restore: Automatically restore terminated droplets from snapshots using stored configuration (region, size, reserved IPs).

• Audit Logging: All operations are logged with timestamps for accountability and debugging.

• Multi-Droplet Operations: Manage multiple droplets in a single command.

• Reserved IP Management: Automatic reassignment of reserved (floating) IPs during restore operations.

• In-Progress Tracking: See snapshots that are currently being created.

• Python API: Programmatic access to all functionality.

Installation

Install from source:

pip install -e .

For development:

pip install -e ".[dev]"

Configuration

OCEA requires a DigitalOcean API token. Configure it using one of these methods (in priority order):

1. `.env` file in the current directory:

   DO_API_TOKEN=your_token_here

2. Environment Variable (recommended):

   export DO_API_TOKEN=your_token_here
   # or
   export DIGITALOCEAN_TOKEN=your_token_here

3. Config file at ~/.config/ocea/token (Linux/macOS) or %APPDATA%\ocea\token (Windows)

Optional: Set a custom database path:

export OCEA_DB_PATH=/path/to/ocea.db

Quick Start

# Set your API token
export DO_API_TOKEN=your_token_here

# List all droplets
ocea list

# Check inventory status
ocea status

# Create a new droplet
ocea new my-server -r nyc1 -s s-1vcpu-1gb -i ubuntu-24-04-x64

# Create a snapshot
ocea snap create my-server

# Gracefully shut down
ocea down my-server

# Terminate with auto-snapshot (for cost savings)
ocea down my-server --terminate

# Restore from snapshot
ocea up my-server

Commands

ocea list                      # All droplets and snapshots
ocea list --droplets           # Only droplets
ocea list --snaps              # Only snapshots
ocea list -r nyc1              # Filter by region
ocea list -r nyc1 -r sfo3      # Filter by multiple regions
ocea list --local              # From local database only
ocea list --json               # Output as JSON

ocea status                    # Summary of all droplets
ocea status my-server          # Details for specific droplet
ocea status --local            # From local database only
ocea status --json             # Output as JSON

ocea up my-server              # Power on or restore
ocea up server1 server2        # Multiple droplets
ocea up --no-attach-ip srv     # Skip reserved IP reassignment
ocea up --json my-server       # Output as JSON

ocea down my-server                        # Graceful shutdown
ocea down my-server --terminate            # Terminate with auto-snapshot
ocea down my-server --terminate --no-snapshot  # Terminate without snapshot
ocea down --json my-server                 # Output as JSON

# Basic creation
ocea new my-server -r nyc1 -s s-1vcpu-1gb -i ubuntu-24-04-x64

# With SSH key and tags
ocea new my-server -r nyc1 -s s-1vcpu-1gb -i ubuntu-24-04-x64 \
    --ssh-key my-key --tag production --tag web

# With all options
ocea new my-server -r nyc1 -s s-1vcpu-1gb -i ubuntu-24-04-x64 \
    --ssh-key my-key --backups --ipv6 --monitoring

ocea snap list                 # List all snapshots
ocea snap create my-server     # Create a snapshot
ocea snap delete 123456789     # Delete by ID
ocea snap delete snap1 snap2   # Delete multiple
ocea snap list --json          # Output as JSON

ocea reboot my-server          # Reboot single droplet
ocea reboot srv1 srv2 srv3     # Reboot multiple droplets
ocea reboot --json my-server   # Output as JSON

Python API

OCEA provides a Python API for programmatic access:

from ocea.api import OCEA

# Initialize (uses environment config)
ocea = OCEA()

# List droplets
droplets = ocea.list_droplets()
for d in droplets:
    print(f"{d.name}: {d.status} ({d.public_ip})")

# Create a droplet
droplet = ocea.create_droplet(
    name="my-server",
    region="nyc1",
    size="s-1vcpu-1gb",
    image="ubuntu-24-04-x64"
)

# Create a snapshot
snapshot = ocea.create_snapshot("my-server", "my-server-backup")

# Terminate (creates snapshot by default)
ocea.terminate("my-server")

# Restore from snapshot
ocea.power_on("my-server")

Database Schema

OCEA maintains a local SQLite database with the following tables:

• droplets: Stores droplet metadata (name, region, size, IPs, status)

• snapshots: Tracks snapshots and their associated droplets

• floating_ips: Maps reserved IPs to droplets

• actions: Audit log of all operations

Development

Setup:

make bootstrap     # Create virtualenv and install dependencies
make precommit     # Install pre-commit hooks

Run tests:

make test          # Unit + integration tests (cached)
make test-all      # Full test suite with coverage

Run linting:

make lint          # Check with Ruff
make format        # Auto-fix with Ruff

Build:

make build         # Build wheel and sdist
make version       # Print current version

License

MIT License. See LICENSE file for details.

Author

Kevin Steptoe