# atlas-runner

A runtime abstraction layer for ATLAS. Provides a library and CLI that launches and manages workloads using Docker (v0), with a backend interface designed to support Apptainer/Singularity in future releases. Used by atlas-agent for deterministic container execution, lifecycle control, status, logs, and resource enforcement.

## Requirements

- Python >= 3.11
- Docker Engine (accessible via `docker` CLI)

## Installation

```bash
pip install atlas-runner
```

For development:

```bash
pip install -e ".[dev]"
```

## Quickstart

### Library usage

```python
from atlas_runner import Runner, RunSpec, create_backend

# Create a runner with the Docker backend
runner = Runner(create_backend("docker"))

# Pull an image and run a container
runner.pull("alpine:latest")
result = runner.run(RunSpec(
    name="my-task",
    image="alpine:latest",
    command=["echo", "hello"],
))
print(result.container_id, result.started_at)

# Check status and fetch logs
status = runner.status("my-task")
print(status.state, status.exit_code)
logs = runner.logs("my-task")

# Clean up
runner.destroy("my-task")
```

### CLI usage

```bash
# Authenticate with a registry
atlas-runner login registry.io -u user --password-stdin < token.txt

# Pull an image
atlas-runner pull alpine:latest

# Run a container with resource limits
atlas-runner run --name my-task --image alpine:latest \
    --cmd echo --cmd hello \
    --cpu-cores 4 --memory-gb 16

# Run with GPU access
atlas-runner run --name gpu-task --image nvidia/cuda:12.0-base \
    --gpu 0 --gpu 1 \
    --shell "python train.py"

# Check status (human-readable or JSON)
atlas-runner status my-task
atlas-runner --json status my-task

# View logs
atlas-runner logs my-task

# List all containers
atlas-runner ps
atlas-runner --json ps

# Stop and remove
atlas-runner destroy my-task
```

## Configuration

| Option | CLI Flag | Description |
|---|---|---|
| Backend | `--backend docker` | Container runtime backend (default: `docker`) |
| Docker host | `--docker-host tcp://remote:2375` | Docker daemon socket URL |
| JSON output | `--json` | Output structured JSON instead of human-readable text |

## Development

```bash
# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Lint and format
ruff check src/ tests/
ruff format --check src/ tests/

# Type check
mypy src/
```

## API Reference

See [docs/api.md](docs/api.md) for the full API reference.

## License

MIT — see [LICENSE](LICENSE) for details.
