cps

cps даёт аппаратно-изолированную Linux microVM, которая грузится мгновенно: root по SSH, персистентный диск и публичный HTTPS-ingress — всё управление собрано в одном CLI. Временные машины с автоматическим освобождением ресурсов: поднял, поработал, забыл — TTL уберёт за тобой.

Под капотом — Firecracker + jailer: каждая машина это отдельная виртуалка с собственным ядром, изолированная на уровне железа, а не контейнер, делящий ядро с соседями.

Что дальше

Быстрый старт — от установки до работающей машины за пару минут.
Справочник CLI — все команды: new, ssh, expose, snapshot, backup и т.д.
API и авторизация — токены, org-scoping и REST для автоматизации помимо CLI.

Что умеет microVM

Мгновенный старт — загрузка за ~секунду, а не десятки секунд, как полноценная VM.
Сильная изоляция — отдельное ядро на каждую машину (Firecracker + jailer), сеть между гостями изолирована. Не «контейнер с общим ядром».
Настоящий Linux — root, произвольные пакеты, системные вызовы, свой диск. Не sandbox с урезанным рантаймом.
Персистентность и переносимость — диск сохраняется между запусками; snapshot/backup можно восстановить на другом хосте.
Временность по умолчанию — TTL автоматически освобождает ресурсы; постоянные машины — по явному запросу (--ttl 0).

Это альфа по приглашениям. Вопросы, баги, идеи → чат сообщества @cps_run в Telegram.

Быстрый старт

Путь от нуля до работающей машины. Нужен токен доступа — его выдаёт команда cps (альфа по приглашениям).

1. Установка CLI

curl -fsSL https://cps.run/install.sh | sh

Скрипт скачивает бинарь cps под вашу ОС/архитектуру и ставит его в ~/.local/bin. Если этого каталога нет в PATH:

export PATH="$HOME/.local/bin:$PATH"

Поддержка: Linux и macOS, x86_64 или arm64. Проверить установку:

cps version

2. Вход

cps login --token <ваш-токен>

По умолчанию API — https://cps.run. Выберите проект вашей организации:

cps project list          # показывает проект "default", созданный для вашей org
cps project use <prj_id>  # из списка выше

3. Запуск машины

cps new ubuntu --name dev --start --wait

По умолчанию: 1 vCPU, 512 MiB RAM, диск 4 GiB и TTL 24 часа (машина сама удалится через сутки, чтобы ничего не осталось работать по забывчивости). Переопределить: --cpu, --ram 2G, --disk 10G, --ttl 2h. Для постоянной машины (без авто-удаления) — --ttl 0.

4. Работа с машиной

cps ssh dev                       # root-шелл по SSH
cps exec dev -- uname -a          # разовая команда
cps cp ./file dev:/root/          # скопировать файл внутрь
cps expose dev 8080               # опубликовать порт по публичному HTTPS
cps metrics dev                   # живые CPU / память
cps ps                            # список ваших машин

cps expose вернёт публичный URL вида https://rte-....cps.run, проксирующий на указанный порт внутри машины.

5. Snapshot и backup

Машину нужно остановить (cps stop):

cps stop dev
cps snapshot create dev --name base --wait     # быстрая точка восстановления
cps backup create dev --name daily --wait      # durable-копия вне хоста (S3)
cps snapshot restore <snap> --name dev2 --start --wait

Snapshot — быстрый слепок диска (точка восстановления). Backup — durable-копия в off-host хранилище (S3), переживает потерю хоста и восстанавливается на любом хосте флота.

6. Уборка

cps rm dev --yes

Лимиты и этикет (альфа)

У вашей org есть квота ресурсов и лимит на число машин. cps предупредит при достижении лимита.
Машины аппаратно изолированы (Firecracker + jailer) и не видят друг друга.
Пожалуйста, без злоупотреблений (спам, сканирование, майнинг). Это приватная альфа.
Вопросы, баги, идеи → чат @cps_run в Telegram.

Если что-то не так

cps ssh завис → Ctrl-C и повторить; про устойчивые зависания напишите в чат.
401/403 → токен истёк или выбран не тот проект (cps project use).
cps whoami показывает, под кем вы аутентифицированы.

Справочник CLI

Все команды работают в контексте активного проекта (см. cps project use) и требуют входа (cps login). Глобальный флаг --json выводит машиночитаемый JSON вместо таблиц.

Окружение переопределяет конфиг: CPS_API_URL, CPS_TOKEN, CPS_PROJECT_ID.

Аутентификация и контекст

Команда	Назначение
`cps login --token <t>`	Сохранить токен и адрес API в конфиг.
`cps whoami`	Показать текущего пользователя/org.
`cps version`	Версия CLI.
`cps project list`	Проекты вашей org.
`cps project use <prj_id>`	Сделать проект активным.
`cps project create <name>`	Создать проект.

Машины

cps new <image> --name <n> [--start] [--wait] [опции]

Флаг	По умолчанию	Описание
`--cpu <n>`	1	vCPU.
`--ram <n>`	512 (MiB)	Память; принимает `2G`, `512M`.
`--disk <n>`	4	Диск в GiB.
`--ttl <d>`	24h	Время жизни; `0` — постоянная машина. Принимает `2h`, `30m`, `7d`.
`--ssh-key <path>`	—	Публичный ключ, который прописать внутрь.
`--region <r>`	—	Предпочитаемый регион/хост.
`--require <label>`	—	Требуемые метки хоста (можно несколько).
`--start`	—	Сразу запустить после создания.
`--wait`	—	Дождаться готовности.

Команда	Назначение
`cps ps [--all]`	Список машин (`--all` включает удалённые).
`cps status <m>`	Подробный статус машины.
`cps start <m>` / `cps stop <m>`	Запустить / остановить.
`cps rm <m> --yes`	Удалить машину.
`cps wait <m> --timeout <s>`	Дождаться готовности.
`cps clone <src> --name <n> [--start] [--wait]`	Клонировать машину.
`cps console <m>`	Подключиться к серийной консоли.

Доступ и файлы

Команда	Назначение
`cps ssh <m> [--identity <key>] [-- <cmd>]`	Root-шелл по SSH (через туннель); с командой — выполнить и выйти.
`cps exec <m> [--timeout <s>] -- <cmd>`	Разовая команда, вернуть stdout/stderr.
`cps cp [--recursive] <src> <dst>`	Копировать файлы (`m:/path` — путь внутри машины).
`cps ssh-proxy <project> <m>`	Вывести `ProxyCommand` для нативного `ssh`/`scp`.

Публикация портов (ingress)

Команда	Назначение
`cps expose <m> <port>`	Публичный HTTPS-URL на внутренний порт; печатает `https://rte-….cps.run`.
`cps routes`	Активные маршруты.
`cps unexpose <selector>`	Снять маршрут.

Snapshot и backup

Машина должна быть остановлена. Snapshot — быстрая точка восстановления; backup — durable-копия в S3 (переносима между хостами).

Команда	Назначение
`cps snapshot create <m> --name <n> [--wait]`	Снять snapshot.
`cps snapshot list [<m>]`	Список snapshot’ов.
`cps snapshot show <snap>`	Детали.
`cps snapshot restore <snap> --name <n> [--start] [--wait]`	Восстановить в новую машину.
`cps snapshot rm <snap> [--yes]`	Удалить.
`cps backup create <m> --name <n> [--wait]`	Создать backup.
`cps backup list [<m>]` / `show <b>` / `restore <b> …` / `rm <b> [--yes]`	Управление backup’ами.

Метрики

Команда	Назначение
`cps metrics <m>`	Текущие CPU / память.
`cps metrics <m> --history [--window <s>]`	История за окно (из ClickHouse).
`cps operations`	Недавние асинхронные операции проекта.

Секреты

Секреты проекта шифруются at-rest и доступны машинам проекта.

Команда	Назначение
`cps secret set KEY=VALUE …`	Задать секреты.
`cps secret list`	Имена секретов (без значений).
`cps secret rm <name>`	Удалить.

Токены

Команда	Назначение
`cps token create [--name <n>] [--ttl <d>]`	Выпустить токен (секрет показывается один раз).
`cps token list`	Ваши токены.
`cps token rm <token_id>`	Отозвать.

Образы

Реестр образов в S3; хосты подтягивают образ по требованию (см. также API).

Команда	Назначение
`cps image push <id> --kernel <vmlinux> --rootfs <ext4> [--name] [--version] [--arch] [--boot-args]`	Загрузить и зарегистрировать образ.
`cps image list`	Доступные образы.
`cps image rm <id> [--yes]`	Удалить образ из реестра и S3.

Администрирование

Требует admin-токена. Обычным пользователям недоступно.

Команда	Назначение
`cps admin org create <name> --cpu --ram --disk --max-machines`	Создать org с квотой (авто-создаёт проект `default`).
`cps admin org list` / `usage <org>`	Список org / потребление vs квота.
`cps admin org quota set <org> …`	Изменить квоту.
`cps admin user create <org> --name [--email]` / `user rm <user>`	Пользователи.
`cps admin token issue <org> <user> [--name] [--ttl]`	Выпустить пользовательский токен.
`cps admin hosts` / `cps admin host <inspect\|drain\|cordon\|uncordon\|tag> <host>`	Управление флотом.

API и авторизация

CLI — тонкая обёртка над REST API control-plane. Тот же API можно вызывать напрямую для автоматизации.

База и авторизация

Base URL: https://cps.run (переопределяется CPS_API_URL).
Авторизация: заголовок Authorization: Bearer <token>. Токен выпускается через cps token create (или админом через cps admin token issue).
Scoping: токен привязан к вашей организации; вы видите и меняете только ресурсы своей org.
Токен = секрет: показывается один раз, храните вне git, отзывается через cps token rm.

Проверка живости (без авторизации):

curl -s https://cps.run/healthz
# {"status":"ok"}

Кто я:

curl -s https://cps.run/v1/whoami -H "Authorization: Bearer $CPS_TOKEN"

Модель ресурсов

org ──┬── project ──┬── machine ──┬── snapshot
      │             │             └── backup
      │             └── route (ingress) / secret
      └── (квота: cpu / ram / disk / max-machines)

Почти все ресурсы скоупятся проектом и живут под /v1/projects/{project_id}/…. Проект по умолчанию — prj_default.

Основные эндпоинты

Метод + путь	Назначение
`GET /v1/whoami`	Текущий principal.
`GET /v1/projects`	Проекты org.
`GET /v1/projects/{p}/machines`	Список машин (`?include_deleted=true` — с удалёнными).
`POST /v1/projects/{p}/machines`	Создать машину (JSON-тело: image, resources, ttl…).
`POST /v1/projects/{p}/machines/{m}:start` \| `:stop`	Запустить / остановить (async-операция).
`DELETE /v1/projects/{p}/machines/{m}`	Удалить.
`GET /v1/projects/{p}/operations/{op}`	Статус асинхронной операции.
`GET \| POST /v1/projects/{p}/snapshots`	Список / создание snapshot’ов.
`GET \| POST /v1/projects/{p}/backups`	Список / создание backup’ов.
`GET \| POST /v1/projects/{p}/routes`	Ingress-маршруты (`expose`).
`GET \| POST \| DELETE /v1/tokens`	Управление токенами.
`GET \| POST /v1/images`	Реестр образов.

Асинхронные операции

Мутирующие действия (create/start/stop/snapshot/backup/restore) возвращают operation и выполняются асинхронно. Дождитесь завершения опросом статуса:

# создать машину → получить operation_id из ответа, затем опрашивать:
curl -s https://cps.run/v1/projects/prj_default/operations/$OP \
  -H "Authorization: Bearer $CPS_TOKEN"
# статус переходит pending → running → succeeded | failed

CLI делает это за вас при флаге --wait.

Пример: список машин

curl -s https://cps.run/v1/projects/prj_default/machines \
  -H "Authorization: Bearer $CPS_TOKEN" | jq .

Коды ошибок

Код	Значение
`401`	Нет/невалидный токен.
`403`	Токен валиден, но нет прав на ресурс (чужая org / admin-путь).
`404`	Ресурс не найден в вашем scope.
`409`	Конфликт состояния (например, действие над машиной в неподходящем статусе).
`429`	Превышен rate limit; см. заголовок `Retry-After`.

API находится в активной разработке (альфа) и может меняться. Для стабильных сценариев используйте CLI. Полный контракт запросов/ответов — в репозитории contracts.

MCP и среда для агентов

cps-mcp отдаёт cps как инструменты Model Context Protocol, так что любой MCP-совместимый агент (Claude Code, Claude Desktop, …) может создавать изолированные Linux-песочницы (sandbox), запускать в них код, публиковать порты и удалять их — всё через публичный API cps.

Sandbox (песочница) — это агентское имя для эфемерной machine на уровне MCP. Это Firecracker-микроВМ с аппаратной изоляцией, диском на время задачи, исходящей сетью, опциональным HTTPS-превью и автоматическим TTL — агент может запускать недоверенный код и не оставлять за собой ресурсов.

cps-mcp работает по MCP через stdio и поставляется внутри CLI cps — установка CLI ставит и cps-mcp.

1. Установка и токен

Установите CLI (подробнее — Быстрый старт):

curl -fsSL https://cps.run/install.sh | sh
cps version          # подтверждает, что установлены и `cps`, и `cps-mcp`

Войдите и создайте токен для агента (показывается один раз):

cps login --token <ваш-токен>
cps token create --ttl 24h --name mcp

2. Конфигурация

cps-mcp берёт настройки из окружения, а после cps login подхватывает конфиг CLI cps (так что CPS_TOKEN можно не задавать, если вы уже вошли):

Переменная	Обязательна	По умолчанию	Назначение
`CPS_TOKEN`	да*	—	Токен cps (`cpsk_…`). *Не нужна, если `cps login` уже настроил CLI.
`CPS_API_URL`	нет	`https://cps.run`	Базовый URL control-plane (например, лабораторный).
`CPS_PROJECT_ID`	нет	определяется автоматически	Проект для создания песочниц; выводится из org токена, если не задан.

3. Подключение MCP-клиента

Claude Code — одной командой:

claude mcp add cps -e CPS_TOKEN=cpsk_ваш_токен -- cps-mcp

Claude Desktop / любой MCP-клиент — добавьте в конфиг mcpServers:

{
  "mcpServers": {
    "cps": {
      "command": "cps-mcp",
      "env": { "CPS_TOKEN": "cpsk_ваш_токен", "CPS_API_URL": "https://cps.run" }
    }
  }
}

Проверьте подключение командой /mcp — сервер cps должен показываться как подключённый с 8 инструментами.

4. Инструменты

Инструмент	Назначение
`create_sandbox(image?, ttl_seconds?)`	Запустить эфемерную микроВМ, дождаться готовности, вернуть `sandbox_id`. Авто-удаление по TTL (по умолчанию 900с).
`run(sandbox_id, command[], timeout_secs?)`	Выполнить argv-массив в песочнице; возвращает `exit_code`, `stdout`, `stderr`. Не парсится шеллом — для пайпов/glob используйте `["sh", "-c", "…"]`.
`write_file(sandbox_id, path, content)`	Записать текстовый файл в песочнице.
`read_file(sandbox_id, path)`	Прочитать текстовый файл из песочницы.
`expose(sandbox_id, port)`	Опубликовать порт по публичному HTTPS-URL.
`destroy(sandbox_id)`	Удалить песочницу и её маршруты.
`fork_sandbox(sandbox_id, ttl_seconds?)`	Клонировать диск песочницы в новую готовую песочницу (источник кратко останавливается для консистентной копии).
`list_sandboxes()`	Список песочниц в проекте.

Типичный сценарий агента:

create_sandbox → sandbox_id
write_file(sandbox_id, "/root/app.py", "…")
run(sandbox_id, ["python3", "/root/app.py"])
expose(sandbox_id, 8080) → публичный HTTPS-URL
destroy(sandbox_id) (или дождаться удаления по TTL)

5. Плагин и skill для Claude Code

Для Claude Code установка плагина cps-agent-runtime даёт агенту сразу и MCP-инструменты cps, и skill cps-agent-runtime, который учит агента пользоваться ими правильно (уборка по TTL, argv против шелла, освобождение маршрутов при destroy).

Плагин регистрирует команду cps-mcp — бинарь уже должен быть в PATH (шаг 1). Установка с Git-ремоута:

/plugin marketplace add https://git.codelab.vc/cps/cli
/plugin install cps-agent-runtime@cps

Или из локальной копии репозитория cli:

/plugin marketplace add /абсолютный/путь/к/cli
/plugin install cps-agent-runtime@cps

Дальше просите естественным языком — например, «запусти этот скрипт в изолированной песочнице cps и покажи вывод» — и skill проведёт create_sandbox → write_file/run → destroy.

6. Обновление

cps-mcp, CLI и плагин обновляются независимо — команды cps update пока нет.

CLI + cps-mcp (один бинарь, один шаг) — перезапустите установщик, он заменит бинарь на месте, затем перезапустите MCP-клиент, чтобы он заново поднял cps-mcp:

curl -fsSL https://cps.run/install.sh | sh
cps version          # проверьте новую версию

Либо из исходников:

git pull && cargo install --path . --locked --force

Плагин + skill — обновите маркетплейс Claude Code (заново тянет репозиторий cli), затем переустановите плагин:

/plugin marketplace update cps
/plugin install cps-agent-runtime@cps
/reload-plugins            # применить изменения без перезапуска сессии

Плагин только регистрирует cps-mcp — обновление плагина не обновляет бинарь. Чтобы получить новое поведение инструментов, обновите CLI (выше).

Примечания (альфа)

Публичные HTTPS-превью через expose требуют слоя маршрутизации cps. На одно-хостовых лабораторных стендах запись маршрута создаётся, но трафик пока не обслуживается.
cps-mcp общается только с публичным API cps, поэтому работает с любым доступным control-plane через CPS_API_URL.
Новые версии CLI появляются на https://cps.run/install.sh только после того, как команда cps выпустит релиз — повторный запуск установщика берёт текущую.

Keyboard shortcuts

cps — документация