# Imagens O que uma máquina inicializa: uma imagem do Arrakis com SSH e as ferramentas de sempre, ou uma imagem sua, pública ou privada. ## Imagens do Arrakis Uma máquina inicializa uma imagem do Arrakis, a menos que você escolha outra. Cada uma é uma imagem base oficial com SSH, um banner de login e ferramentas do dia a dia: git, git-lfs, tmux, htop, nvtop, rsync, curl, wget, jq e um editor. O Python está no PATH em toda sessão SSH. | Imagem | O que inclui | Imagem Docker | |---|---|---| | PyTorch 2.14 (padrão) | PyTorch 2.14.1, CUDA 13.0, Python 3.12, Ubuntu 24.04 | `goodailabs/arrakis:pytorch-2.14.1-cuda13.0` | | PyTorch 2.14 com o kit de ferramentas CUDA | A mesma, mais o nvcc, os cabeçalhos do CUDA e um compilador | `goodailabs/arrakis:pytorch-2.14.1-cuda13.0-devel` | | Kit de ferramentas CUDA 13.0 | CUDA 13.0.3, cuDNN 9, nvcc, Python 3.12, Ubuntu 24.04 | `goodailabs/arrakis:cuda-13.0.3-devel` | | Ubuntu 26.04 | Python 3.14. O driver da GPU vem da máquina | `goodailabs/arrakis:ubuntu-26.04` | O CUDA 13.0 é a versão que o `pip install torch` instala, então wheels compilados para o PyTorch funcionam. Ele roda em todas as máquinas do Arrakis, Blackwell incluída: cada uma tem um driver NVIDIA da série 580 ou mais recente. As imagens são públicas no Docker Hub, então você pode baixar a mesma no seu computador; `goodailabs/arrakis:latest` é a padrão. Ao entrar, você vê as GPUs da máquina, a imagem e o espaço livre em disco: ```text 6 × NVIDIA RTX A4000, 16 GB each PyTorch 2.14.1, CUDA 13.0, Python 3.12.3, Ubuntu 24.04.5 LTS 32 CPU cores, 125 GB memory, 412 GB free in /workspace ``` Trabalhe em `/workspace`. Tudo o que está na máquina, `/workspace` incluído, é apagado quando ela para. ## Suas próprias imagens Qualquer imagem funciona: vLLM, SGLang, contêineres do NVIDIA NGC ou a imagem do seu time, pública ou privada. - Em **Images**, escolha **Add an image** e cole o nome do jeito que o `docker pull` aceita, como `vllm/vllm-openai:v0.11.0`. Para uma imagem pública, você também pode escolher **Your own image** ao alugar. - O Arrakis consulta primeiro o registro da imagem: ela precisa existir, poder ser baixada e ter uma versão linux/amd64. Um erro de digitação ou um token errado é recusado antes de qualquer cobrança. - Registros: Docker Hub, GitHub (`ghcr.io`), Amazon ECR e ECR Public, Google (Artifact Registry e `gcr.io`), Azure (`azurecr.io`), NVIDIA NGC (`nvcr.io`), Quay, GitLab e Microsoft (`mcr.microsoft.com`), ou o seu próprio: Harbor, Artifactory, Nexus, um GitLab ou Quay auto-hospedado, qualquer registro pelo nome DNS público, como `registry.example.com:5000/team/app:v1`. - O SSH é adicionado a qualquer imagem na inicialização, então você entra como root do mesmo jeito. A imagem precisa ter um shell. - A primeira inicialização em uma máquina baixa a imagem. Imagens grandes demoram mais: uma imagem de 12 GB pode levar de 10 a 20 minutos em uma rede lenta. ### Imagens privadas Marque **It's private: log in to pull it** ao adicionar a imagem e informe as credenciais que o `docker login` pediria. O Arrakis verifica a imagem com elas antes de salvar, guarda as credenciais criptografadas e só as usa para baixar esta imagem quando você aluga. A senha nunca mais é exibida. | Registro | Nome de usuário | Senha ou token | |---|---|---| | Docker Hub | Seu nome de usuário do Docker Hub | Um token de acesso pessoal só com permissão de leitura | | GitHub (`ghcr.io`) | Seu nome de usuário do GitHub | Um token clássico com apenas `read:packages` | | Amazon ECR (`.dkr.ecr..amazonaws.com`) | Um ID de chave de acesso | A chave de acesso secreta correspondente | | Google (`-docker.pkg.dev`, `gcr.io`) | `_json_key` | A chave JSON de uma conta de serviço com o papel Artifact Registry Reader | | Azure (`.azurecr.io`) | Um token de repositório ou uma entidade de serviço | A senha correspondente, só com permissão para baixar imagens | | NVIDIA NGC (`nvcr.io`) | `$oauthtoken` | Sua chave de API do NGC | | GitLab (`registry.gitlab.com`) | O nome de usuário de um token de implantação | O token de implantação, com `read_registry` | | Quay | Uma conta de robô | O token dela | | Seu próprio registro | O nome de usuário que ele exige | A senha ou o token correspondente | - **Amazon ECR**: use um usuário da AWS que só possa baixar imagens (a política `AmazonEC2ContainerRegistryReadOnly`). A cada aluguel, o Arrakis troca a chave por um login novo, válido por 12 horas e só para baixar imagens (o que o `aws ecr get-login-password` imprime), então a máquina nunca vê a chave em si. - **Seu próprio registro**: as máquinas baixam direto dele, de onde estiverem, então ele precisa responder na internet pública por HTTPS, com um certificado de uma autoridade pública (como o Let's Encrypt). Um registro atrás de uma VPN ou de uma lista de IPs permitidos fica inacessível; um com certificado autoassinado é recusado. - Use um token só de leitura. A máquina baixa a imagem com ele, e a imagem pode continuar em cache nessa máquina depois que o aluguel termina; por isso, não coloque segredos na imagem e passe-os quando ela rodar. - Para trocar um token, escolha **Change login** ao lado da imagem ou salve a mesma imagem de novo com o token novo. Remover a imagem apaga o login dela em todos os lugares onde o Arrakis o guardou. ### Quando a máquina inicia | Opção | O que roda | Use para | |---|---|---| | Wait for me to log in (padrão) | Nada. A máquina espera por você | Treinamento, notebooks, qualquer coisa que você inicie por SSH | | Run the image's command | O entrypoint e o comando da própria imagem | Servidores como vLLM, TGI ou SGLang | | Run a command | Uma linha simples que você fornece, como `python -m http.server 8000` | Um job que começa sozinho | Se o comando terminar, não dá mais para acessar a máquina. Na dúvida, escolha **Wait for me to log in**. Acesse um servidor da máquina pelo SSH: ```sh ssh -L 8000:localhost:8000 root@ -p curl localhost:8000/v1/models ``` ### Variáveis de ambiente Adicione pares `KEY=value` a uma imagem, um por linha. Eles ficam salvos com a imagem; por isso, não coloque segredos neles e defina os segredos por SSH, por exemplo `export HF_TOKEN=...` na sua sessão. ## Pela CLI, pela API e por agentes ```sh arrakis images list arrakis images add vllm/vllm-openai:v0.11.0 --start image arrakis instances create --node-id --image vllm/vllm-openai:v0.11.0 --start image --termination-hours 2 ``` Para uma imagem privada, informe o login, com o token pela stdin, como no `docker login`: ```sh echo "$GITHUB_TOKEN" | arrakis images add ghcr.io/acme/trainer:v3 --username acme-bot --password-stdin arrakis instances create --node-id --template-id --termination-hours 2 ``` ```sh curl -X POST $ARRAKIS_URL/v1/instances -H "Authorization: Bearer $ARRAKIS_TOKEN" -H "Content-Type: application/json" \ -d '{"node_id": "", "name": "vllm", "termination_hours": 2, "ssh_public_key": "ssh-ed25519 AAAA...", "image": "vllm/vllm-openai:v0.11.0", "start": "image"}' ``` - `GET /v1/templates` lista as imagens do Arrakis e as suas; `POST /v1/templates` salva uma (`image`, `start`, `command`, `environment` e, para uma imagem privada, `registry_username` e `registry_password`). A senha é só de escrita: as respostas mostram `private` e `registry_username`. `PATCH /v1/templates/{id}` com os dois campos substitui o login. - `POST /v1/instances` inicializa um `template_id` ou qualquer `image` pública com um `start`. - Via MCP, `list_images` lista as imagens, com as privadas marcadas, e `rent_gpu` aceita `template_id` ou `image`. Mais: [toda a documentação](/pt/docs.md) · [OpenAPI](/openapi.json) · [llms.txt](/pt/llms.txt)