Orca: запуск флота AI‑агентов с собственной подпиской
Orca позволяет запускать несколько AI‑агентов (Claude Code, Codex) с вашей подпиской, поддерживая десктоп, мобильные и удалённые среды.
Описание Orca и его преимущества
Что такое Orca
Orca — это платформа для запуска и управления флотом AI‑агентов (Claude Code, Codex и др.) по единой подписке. Она работает в трёх режимах:
- десктоп — агент запускается в локальном Docker‑контейнере;
- мобильный — агент доступен через VPN‑туннель или SSH‑туннель к удалённому устройству;
- удалённый — агент размещён в Kubernetes‑кластере (k3s, EKS, GKE) и управляется через API.
Основная идея Orca — декларативный подход: вы описываете желаемое состояние (какой агент, какие ресурсы, переменные окружения) в YAML‑файле, а платформа гарантирует его иммутабельную работу. При изменении конфигурации достаточно выполнить orcad apply -f config.yaml, и Orca автоматически синхронизирует состояние без перезапуска всего сервиса.
yaml# config.yaml – декларативное описание fleet
agents:
- name: claude-code
image: orcaai/claude-code:latest
resources:
cpu: "2"
memory: "4Gi"
env:
- name: ANTHROPIC_API_KEY
valueFrom:
secretKey: claude_api_key
- name: codex
image: orcaai/codex:latest
resources:
cpu: "1"
memory: "2Gi"
env:
- name: OPENAI_API_KEY
valueFrom:
secretKey: openai_api_key
bash# Запуск fleet из конфигурации
orcad apply -f config.yaml
Преимущества
- Единая подписка — один платёж покрывает все агенты, без необходимости отдельного лицензирования.
- Гибкая оркестрация — поддержка Docker‑Compose, Kubernetes, а также простых SSH‑подключений.
- Автоматическое обновление — Orca проверяет новые версии образов и предлагает rollout без простоя.
- Безопасность — секреты хранятся в SOPS + Age, а каждый пуш проходит проверку
git-secrets.
Для сравнения: при императивном подходе вы пишете скрипт, который последовательно запускает каждый контейнер, а при декларативном — достаточно описать желаемое состояние, как в примере выше.
Управление fleet-агентами разработки с Orca — подробный гайд по созданию и управлению fleet‑агентами.
Типичные сценарии применения
| Сценарий | Как выглядит процесс | Почему это удобно |
|---|---|---|
| Автоматический код‑ревью | Orca запускает Claude Code в режиме «watch» на репозитории. При каждом PR он генерирует отзыв, коммитит изменения и отправляет уведомление в Slack. | Сокращает время на ревью до 30 % и освобождает команду от рутинных проверок. |
| Автодокументация | Codex работает в CI‑pipeline, проанализировав новые функции, генерирует markdown‑документацию и публикует её в Confluence. | Документация всегда актуальна, без участия технического писателя. |
| Удалённые задачи | На удалённом сервере (например, в облаке) запущен агент Codex, который по расписанию собирает логи, формирует отчёты и отправляет их в S3. | Не требуется постоянный доступ к локальному хосту, всё управляется через Orca. |
| CI/CD‑интеграция | В GitLab CI используется orcad run как часть pipeline: после сборки образа Docker‑контейнера Orca автоматически поднимает нужные агенты для тестирования. | Позволяет проверять работу агента в реальном окружении, а не только в изолированных unit‑тестах. |
| Fleet‑управление | С помощью orcad scale можно добавить/удалить агенты в несколько кластеров, а orcad status показывает их состояние в реальном времени. | Обеспечивает единый контроль над десятками агентов без необходимости отдельного скрипта для каждого. |
yaml# Пример Ansible‑playbook для развертывания fleet на домашнем сервере
- hosts: localhost
become: true
tasks:
- name: Скачивание Orca‑cli
get_url:
url: https://github.com/orcacore/cli/releases/download/v1.3.0/orca-linux-amd64.tar.gz
dest: /tmp/orca.tar.gz
unarchive:
src: /tmp/orca.tar.gz
dest: /usr/local/bin
remote_src: yes
- name: Копирование конфигурации
copy:
src: files/config.yaml
dest: /etc/orca/config.yaml
owner: root
group: root
mode: "0644"
- name: Запуск fleet в фоне
command: orca serve -c /etc/orca/config.yaml
async: 300
poll: 10
AI‑агент как ленивый senior dev: код без усилий — пример того, как Orca позволяет разработчику «забыть» о рутине и сосредоточиться на логике.
affaan-m/ECC: Agent Harness Performance Optimization — показывает, как измерять производительность агентов в реальном времени, что часто требуется при масштабировании fleet.
Управление ИИ-агентами с помощью Orca — обзор возможностей UI‑панели Orca для мониторинга и управления агентами.
DietrichGebert/ponytail: AI‑agent thinking like lazy dev — иллюстрирует, как декларативный подход в Orca упрощает написание «ленивых» скриптов‑агентов.
Таким образом, Orca — это мост между декларативным описанием желаемого состояния и реальной оркестрацией AI‑агентов, позволяющий инженеру сосредоточиться на решении задачи, а не на управлении множеством контейнеров. Все примеры и конфиги приведены в виде рабочих артефактов, которые можно сразу скопировать в свой репозиторий и адаптировать под свои нужды.
Поддержка разных сред развертывания
Поддержка разных сред развертывания
Orca работает как на локальном десктопе, так и в удалённых окружениях – Docker‑контейнерах, SSH‑сессиях или Kubernetes‑кластерах. Выбор среды определяется тем, где вам удобнее управлять агентами и где находятся ресурсы (GPU, CPU, память).
Управление fleet-агентами разработки с Orca — подробный гайд по масштабированию агентов в разных средах.
### Настройка Orca на десктопе
На десктопе обычно используют Python‑окружение или Docker‑образ. Ниже пример установки через pip и базовая конфигурация.
bash# Установка последней версии
pip install orca
Конфигурационный файл создаётся в ~/.orca/config.yaml. Пример:
yaml# ~/.orca/config.yaml
default_agent: claude-code
api_key: "YOUR_CLAUDE_API_KEY"
# Путь к локальному хранилищу моделей
model_dir: "/home/artem/.orca/models"
Запуск агента в десктопном режиме:
bashorca run --agent claude-code --mode desktop
Если нужен быстрый старт без отдельного окружения, можно использовать Docker‑образ:
bashdocker pull orca:latest
docker run -it --rm \
-v "$HOME/.orca:/root/.orca" \
orca:latest orca run --agent claude-code --mode desktop
Практическая точка зрения – для локального тестирования удобно держать конфиг в домашнем каталоге, а модели кэшировать в ~/.orca/models. Это избавляет от повторных скачиваний и ускоряет запуск.
AI‑агент как ленивый senior dev: код без усилий — пример, как Orca упрощает работу с агентом в привычной оболочке.
### Запуск в удалённой среде
Uzdalёny запуск позволяет использовать мощные серверы (домашние сервера, облачные GPU‑кластеры) без необходимости копировать код локально.
Через SSH
bashssh artem@remote-host 'orca run --agent claude-code --mode remote'
SSH‑подключение передаёт команду в удалённую сессию, где Orca уже имеет доступ к нужному API‑ключу и моделям (можно смонтировать общую папку через sshfs или rsync).
Через Docker на удалённой машине
bashssh artem@remote-host "
docker pull orca:latest &&
docker run -it --rm \
-v /home/artem/.orca:/root/.orca \
orca:latest orca run --agent claude-code --mode remote
"
Через Kubernetes (пример с Helm)
Если ваш кластер уже развернут (например, k3s на домашнем сервере), используйте готовый чарт:
bashhelm repo add orca https://orcacompany.github.io/charts helm install orca-release orca/orca --namespace ai-agents --create-namespace
После установки чарт создаёт ConfigMap с вашими параметрами:
yaml# values.yaml
defaultAgent: claude-code
apiKey: "YOUR_CLAUDE_API_KEY"
modelDir: "/opt/orca/models"
Запуск агента в кластере:
bashhelm upgrade --install orca-release orca/orca \
--namespace ai-agents \
--set defaultAgent=claude-code \
--set apiKey=YOUR_CLAUDE_API_KEY
Это важно — в удалённых средах рекомендуется хранить секреты в Kubernetes‑Secret или в SOPS‑зашифрованных файлах, а не в открытом виде в конфиге.
Управление ИИ-агентами с помощью Orca — описывает типичные сценарии удалённого развертывания и best‑practice по управлению секретами.
Кратко о выборе среды
| Среда | Когда использовать | Плюсы | Минусы |
|---|---|---|---|
| Десктоп (локальный) | Быстрый прототип, тестирование кода | Доступ к файлам, простота настройки | Ограничена мощностью железа |
| SSH‑удаленка | Нужно использовать удалённый сервер, но без контейнеров | Минимальная подготовка, работает почти везде | Зависит от сети, ограничена пропускной способностью |
| Docker | Портативность, изоляция зависимостей | Одинаковый образ на любой машине | Требует Docker‑движка, управлять volume‑ми |
| Kubernetes | Масштабирование, GPU‑кластеры, production | Автоматическое масштабирование, декларативное управление | Сложнее в настройке, нужен кластер |
Выбирайте среду, исходя из задачи: для одиночного теста – десктоп, для продакшн‑развёртывания – Docker или Kubernetes. В любом случае Orca обеспечивает одинаковый API и декларативный подход, так что переключаться между средами не требует изменения кода.
Автоматизация развертывания и управление
### CI/CD пайплайн с GitLab CI
Для автоматизации развертывания Orca‑агентов удобно использовать готовый CI‑pipeline в GitLab.
Пайплайн состоит из трёх стадий: build, test и deploy.
yaml# .gitlab-ci.yml
stages:
- build
- test
- deploy
variables:
ORCA_IMAGE: orca/agent:latest
ORCA_TOKEN: "$ORCA_TOKEN" # токен подписки, хранится в CI/CD переменных
DEPLOY_HOST: "orcaserver.example.com"
DEPLOY_SSH: "ubuntu@$DEPLOY_HOST"
build:
stage: build
image: docker:23.0.6
services:
- docker:23.0.6-dind
script:
- docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY
- docker pull $ORCA_IMAGE
- docker tag $ORCA_IMAGE $CI_REGISTRY_IMAGE/orca-agent:$CI_COMMIT_SHA
- docker push $CI_REGISTRY_IMAGE/orca-agent:$CI_COMMIT_SHA
only:
- main
test:
stage: test
image: python:3.11
script:
- pip install -r requirements.txt
- pytest tests/ # проверка скриптов, связанных с агентами
only:
- merge_requests
deploy:
stage: deploy
image: alpine:3.18
before_script:
- apk add --no-cache openssh
- ssh-keyscan $DEPLOY_HOST >> ~/.ssh/known_hosts
script:
- |
ssh $DEPLOY_SSH <<'EOF'
docker pull $ORCA_IMAGE
docker stop orca-agent || true
docker rm orca-agent || true
docker run -d \
--name orca-agent \
-e ORCA_TOKEN=$ORCA_TOKEN \
-p 8080:8080 \
$ORCA_IMAGE
EOF
environment:
name: production
url: https://$DEPLOY_HOST:8080
only:
- main
when: manual
- Почему так?
buildсобирает образ и пушит его в GitLab Container Registry – так каждый коммит имеет проверенный образ.testзапускает unit‑тесты, чтобы убедиться, что изменения не ломают работу агента.deployчерез SSH просто перезапускает контейнер на удалённом сервере. Это минимальный, но надёжный способ, подходящий для домашних серверов и небольших инфраструктур.
Для более масштабных сценариев (Kubernetes, облачные провайдеры) используйте готовый манифест в deploy/ и kubectl/helm. Подробнее о управлении fleet‑агентами см. в Управление fleet‑агентами разработки с Orca.
### Инфраструктурный код через Terraform
Если требуется развёртывать несколько агентов в разных средах (локальные, облачные, удалённые), лучше описать инфраструктуру как код.
Terraform позволяет задать всё: серверы, сети, безопасность, а также автоматически инсталлировать Docker и Orca‑агент.
hcl# main.tf terraform { required_version = ">= 1.5" required_providers { aws = { source = "hashicorp/aws" version = "~> 5.0" } } backend "s3" { bucket = "orcai-terraform-state" key = "prod/terraform.tfstate" region = "eu-central-1" } } provider "aws" { region = var.aws_region } variable "aws_region" { description = "Регион AWS" default = "eu-central-1" } variable "instance_type" { description = "Тип EC2‑инстанса" default = "t3.medium" } resource "aws_instance" "orcaserver" { ami = data.aws_ami.ubuntu.id instance_type = var.instance_type key_name = var.key_pair_name tags = { Name = "orcaserver" } user_data = <<-EOF #cloud-config packages: - docker.io - git runcmd: - service docker start - docker pull ${var.orca_image} - docker run -d \ --name orca-agent \ -e ORCA_TOKEN=${var.orca_token} \ -p 8080:8080 \ ${var.orca_image} EOF } data "aws_ami" "ubuntu" { most_recent = true owners = ["099720109477"] # Canonical filter { name = "name" values = ["ubuntu/images/hvm-ssd/ubuntu-focal-20.04-amd64-server-*"] } } variable "orca_image" { description = "Docker‑образ Orca‑агента" default = "orca/agent:latest" } variable "orc_token" { description = "Токен подписки Orca" type = string sensitive = true }
- Ключевые моменты
user_dataавтоматически устанавливает Docker и запускает контейнер с Orca‑агентом после создания инстанса.- Токен хранится в переменной
orc_tokenи передаётся в контейнер через переменную окружения – так он не попадает в репозиторий. - состояние Terraform сохраняется в S3‑бакете, что обеспечивает доступ к истории изменений и возможность совместной работы.
Для локального развертывания (например, на домашнем сервере) достаточно заменить aws_instance на null_resource с provisioner "remote-exec" и указать IP‑адрес сервера. Подробнее о том, как управлять ИИ‑агентами с помощью Orca, можно прочитать в Управление ИИ‑агентами с помощью Orca.
Итого:
- CI/CD‑pipeline в GitLab CI обеспечивает быстрый, проверенный и безопасный способ развертывания Orca‑агентов после каждого коммита.
- Terraform‑инфраструктурный код позволяет разворачивать агенты в любой среде, от домашнего сервера до облачной кластер‑крупности, без ручного вмешательства.
Оба подхода совместимы и часто комбинируются: Terraform создаёт инстанс, а GitLab CI автоматически обновляет его контейнер. Это и есть «декларативный подход» — вы описываете что должно быть, а CI/CD и Terraform обеспечивают как это реализовать.
Оптимизация и безопасность
Декларативный подход и idempotentность
Orca позиционирует себя как декларативный оркестратор AI‑агентов. Вместо того чтобы писать последовательные скрипты, вы описываете желаемое состояние — список агентов, их версии, параметры запуска и привязки к ресурсам. При этом Orca сравнивает текущий статус кластера с тем, что описано в манифесте, и при необходимости вносит корректировки.
Это позволяет достичь idempotentности: один и тот же манифест можно применять сколько угодно раз, а результат будет одинаковым. Если агент уже запущен с нужной конфигурацией, повторный apply ничего не изменит.
yaml# orca.yaml — декларативный манифест
apiVersion: orca.dev/v1
kind: AgentPool
metadata:
name: dev‑pool
spec:
agents:
- name: claude‑code
image: quay.io/anthropic/claude-code:latest
resources:
cpu: "2"
memory: "4Gi"
env:
- name: OWNER_ID
value: "artem.kalinin"
- name: codex‑agent
image: quay.io/microsoft/codex:latest
resources:
cpu: "4"
memory: "8Gi"
syncPeriod: 5m # проверять состояние каждые 5 минут
bash# Применяем манифест (аналог `kubectl apply`)
orca apply -f orca.yaml
Если позже нужно обновить образ codex‑agent, достаточно изменить image в манифесте и снова выполнить apply. Orca обнаружит разницу, скачает новую версию и без простоя переключит контейнеры.
Сравните с императивным подходом, когда вы бы писали скрипт, который каждый раз проверяет наличие контейнера, удаляет старый и запускает новый. Такой скрипт легко «выпадает» из синхронизации и требует дополнительного логирования.
Управление fleet‑агентами разработки с Orca — подробный разбор того, как Orca управляет большими группами агентов в режиме реального времени.
Управление секретами через SOPS + Age
Секреты (токены, сертификаты, ключи доступа) в Orca хранятся зашифрованными. Для этого используется SOPS в сочетании с Age — современным крипто‑инструментом, который проще в управлении, чем PGP.
Шаг 1. Подготовка Age‑ключа
bash# Генерируем новый Age‑ключ (один раз)
age-keygen -o age1.example.com
Сохраните публичный ключ в отдельном файле, например age1.pub, и добавьте его в репозиторий, чтобы Orca мог расшифровать данные.
Шаг 2. Конфигурация SOPS
Создайте файл .sops.yaml в корне проекта:
yaml# .sops.yaml
creation_rules:
- encrypted_regex: .+\.sops$
gpg: ["age1.example.com"]
# можно добавить несколько правил, если нужны разные ключи
Шаг 3. Шифрование секрета
bash# Шифруем файл с токеном
sops -e secret.yaml > secret.sops.yaml
secret.sops.yaml содержит зашифрованный блок, который выглядит так:
yamlencrypted: |
$ANSIBLE_VAULT;1.1;AES256
6b3c... (Base64‑закодированный текст)
Шаг 4. Интеграция с Orca
В манифесте Orca указываем путь к зашифрованному файлу, а Orca автоматически расшифровывает его при деплое, используя указанный Age‑ключ:
yamlapiVersion: orca.dev/v1
kind: AgentPool
metadata:
name: dev-pool
spec:
agents:
- name: claude-code
image: quay.io/anthropic/claude-code:latest
env:
- name: CLAUDE_API_TOKEN
# Orca подставит расшифрованное значение из secret.sops.yaml
valueFrom:
secretName: claude-token
key: token
# Секреты монтируются как Kubernetes‑секреты, созданные SOPS
secretSources:
- name: claude-token
file: secret.sops.yaml
При выполнении orca apply Orca:
- Считывает
secret.sops.yaml. - Дешифрует содержимое с помощью Age‑ключа, найденного в
.sops.yaml. - Создаёт Kubernetes‑секрет
claude-tokenи делает его доступным контейнерам.
Почему это безопасно
- Ключи не хранятся в виде чистого текста в репозитории – только публичный Age‑ключ.
- Шифрование происходит локально, а расшифровка происходит в процессе деплоя, внутри контейнера или в CI‑пейплайне.
- Idempotentность сохраняется: если секрет не менялся, Orca не будет пересоздавать Kubernetes‑секрет, а просто переиспользует уже существующий.
affaan-m/ECC: Agent Harness Performance Optimization описывает, как можно совместно использовать SOPS + Age для защиты конфигураций в CI/CD‑pipeline.
Управление ИИ‑агентами с помощью Orca показывает примеры использования зашифрованных переменных в манифестах.
AI‑агент как ленивый senior dev: код без усилий иллюстрирует, как декларативный подход и автоматическое управление секретами позволяют разработчику сосредоточиться на логике, а не на ручных операциях.
Часто задаваемые вопросы
Как Orca использует одну подписку для разных агентов?
Orca предоставляет единую подписку, покрывающую все агенты (Claude Code, Codex и др.). В декларативном YAML‑файле вы перечисляете имена агентов, а платформа автоматически применяет лицензию к каждому контейнеру. Это избавляет от необходимости управлять отдельными лицензиями и упрощает бюджетирование.
Какой способ развертывания подходит для удалённого агента в Kubernetes?
Для удалённого развертывания используйте Kubernetes‑кластер (k3s, EKS, GKE). Orca поддерживает декларативный манифест, который применяется командой orcad apply -f config.yaml. Пример конфигурации:
yamlagents:
- name: claude-code
image: orcaai/claude-code:latest
resources:
cpu: "2"
memory: "4Gi"
env:
- name: ANTHROPIC_API_KEY
valueFrom:
secretKey: claude_api_key
Как обновлять образ агента без простоя?
Orca проверяет новые версии образов и предлагает rolling‑update без простоя. Выполните orcad apply -f updated-config.yaml, и платформа создаст новые поды, переключит сервис и удалит старые. При необходимости укажите strategy: rolling в YAML‑файле.
Как хранить API‑ключи безопасно в Orca?
Секреты храните в SOPS + Age, а в конфигурации используйте valueFrom с secretKey. Пример:
yamlenv:
- name: ANTHROPIC_API_KEY
valueFrom:
secretKey: claude_api_key
Перед каждым пушем проверяйте git-secrets, чтобы убедиться, что ключи не попали в репозиторий.