Para desenvolvedores

Crie apps para o Space.

Um app do Space é uma página web com um manifesto. Ele abre como janela em todos os aparelhos da pessoa (computador, tablet, celular e relógio) e usa as máquinas dela pela interface App, só com as permissões que pedir.

Começo rápido

Um app é uma pasta com spaceman-app.yaml e uma página. Nada de build obrigatório: HTML, CSS e JavaScript comuns.

Crie a pasta e o manifesto

meu-app/
  spaceman-app.yaml
  index.html
  icone.svg          # opcional
id: contador            # minúsculas, números e hífen
nome: Contador
versao: 0.1.0
icone: "+"
descricao: Conta cliques e lembra em todos os aparelhos.
janela: {w: 420, h: 300}   # guardar os próprios dados não pede capacidade

Escreva a página

<body>
<script src="/app.js"></script>
<div class="bar"><span class="btitle">Contador</span><span id="st"></span></div>
<button id="mais">+1</button> <b id="n">0</b>
<script>
const n = document.getElementById('n')
let total = 0
App.dados.ler('total').then(v => { total = v?.total || 0; n.textContent = total })
document.getElementById('mais').onclick = async () => {
  n.textContent = ++total
  await App.dados.gravar('total', { total })   // igual em todos os aparelhos
  App.estado('salvo', true)
}
</script>

Teste no seu Spaceman

Compacte a pasta (tar czf contador.tar.gz -C contador .) e instale em Loja → Instalados → Instalar de um arquivo. O app aparece no launcher de todos os aparelhos e abre como janela comum. O tutorial mostra também como testar num hub descartável.

Tutorial passo a passo

Do zero até o app instalado e testado, com um exemplo completo. Serve para quem programa e para agentes de IA: tudo aqui foi testado no hub 1.10.12.

Para passar a um agente: tutorial em Markdown e pacote do exemplo.

Suba um hub de teste

Teste num hub descartável, no seu computador (Node 20+, curl, tar, python3). O pacote do servidor é público:

mkdir -p ~/space-teste && cd ~/space-teste
URL=$(curl -s https://space.dynami.art/downloads/spaceman/latest.json | python3 -c "import json,sys;print(json.load(sys.stdin)['servidor']['hub']['url'])")
curl -sfL "$URL" -o hub.tar.gz && tar xzf hub.tar.gz && cd spaceman-hub
SPACEMAN_HUB_PORT=17400 SPACEMAN_HUB_DATA=$HOME/space-teste/dados node hub.js

Ele fica em http://127.0.0.1:17400, só no seu computador, aberto (sem pareamento). O token mestre fica em ~/space-teste/dados/token. Crie um viewport (a área onde as janelas abrem) e veja como a pessoa vê em http://127.0.0.1:17400/view/Teste:

H=http://127.0.0.1:17400; TK=$(cat ~/space-teste/dados/token)
curl -s -X POST -H "x-spaceman-token: $TK" -H 'content-type: application/json' $H/viewport --data '{"op":"criar","novo":"Teste"}'

Conecte a um hub de verdade

No hub de uma pessoa tudo pede token. A pessoa gera um código de uso único (10 min) em Configurações → Aparelhos pareados → Parear um aparelho novo, ou no menu da bolinha → Parear dispositivo. O código vem no link /pair?c=ABCD1234. Troque o código por um token e mande x-spaceman-token em todo pedido:

curl -s -X POST -H 'content-type: application/json' http://<hub>:7334/pair \
  --data '{"c":"ABCD1234","nome":"agente de apps","tipo":"agente"}'
# {"ok":true,"id":"agente-de-apps-c6b7","token":"873e…"}

Esse token tem o acesso de um aparelho da pessoa (inclusive terminal). Use só para instalar e testar; no fim, a pessoa revoga em Configurações → Aparelhos pareados. O hub costuma estar só na rede Tailscale da pessoa: sem acesso a ela, entregue o pacote e a pessoa instala pela Loja.

Escreva o app

Exemplo: Lembretes rápidos. Ele anota, guarda no hub (App.dados) e põe na Agenda da pessoa com aviso em todos os aparelhos (eventos:escrever e notificar).

# lembretes-rapidos/spaceman-app.yaml
# Lembretes rápidos: anota, guarda no hub e põe na Agenda
id: lembretes-rapidos
nome: Lembretes rápidos
versao: 0.1.0
icone: 📝
descricao: Anote algo e, se quiser, ponha na Agenda com aviso em todos os aparelhos.
autor: Exemplo do tutorial
janela: {w: 520, h: 560}
capacidades: [eventos:escrever, notificar]
<!-- lembretes-rapidos/index.html -->
<!doctype html>
<html lang="pt-BR">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Lembretes rápidos</title>
<link rel="stylesheet" href="/app.css">
<style>
  .corpo { padding: 14px; display: flex; flex-direction: column; gap: 10px; }
  form { display: flex; gap: 8px; }
  input { flex: 1; min-width: 0; background: #05070c; color: #e2e8f0; border: 1px solid #26304a; border-radius: 8px; padding: 9px 11px; font: 14px system-ui; }
  button { background: #1e6dff; color: #fff; border: 0; border-radius: 8px; padding: 9px 14px; font: 14px system-ui; cursor: pointer; }
  .item { display: flex; align-items: center; gap: 8px; background: #141926; border: 1px solid #26304a; border-radius: 10px; padding: 10px 12px; color: #e2e8f0; }
  .item span { flex: 1; min-width: 0; overflow-wrap: anywhere; }
  .item button { background: #1c2436; padding: 6px 10px; font-size: 12px; }
  .vazio { color: #8b96ad; font-size: 13px; }
</style>
</head>
<body>
<script src="/app.js"></script>
<div class="bar"><span class="ring"></span><span class="btitle">Lembretes rápidos</span><span id="st"></span></div>
<div class="corpo">
  <form id="novo"><input id="texto" placeholder="O que lembrar?" autocomplete="off"><button>Anotar</button></form>
  <div id="lista"></div>
</div>
<script>
const { el, estado } = App
let itens = []

async function carregar() {
  const r = await App.dados.ler('itens')          // documento JSON do app no hub
  itens = Array.isArray(r && r.itens) ? r.itens : []
  desenhar()
}
async function salvar() {
  const r = await App.dados.gravar('itens', { itens })
  estado(r.err ? 'não salvou: ' + r.err : 'salvo', r.err ? 'erro' : true)
}
function desenhar() {
  const l = document.getElementById('lista'); l.textContent = ''
  if (!itens.length) return el('div', 'vazio', l, 'Nada anotado ainda.')
  itens.forEach((it, i) => {
    const d = el('div', 'item', l)
    el('span', '', d, it.texto)
    el('button', '', d, 'Agenda em 1 h').onclick = () => paraAgenda(it)
    el('button', '', d, '✕').onclick = () => { itens.splice(i, 1); desenhar(); salvar() }
  })
}
// coleção central da pessoa: o compromisso aparece na Agenda e avisa em todos os aparelhos
async function paraAgenda(it) {
  const r = await App.colecao('eventos').criar({ titulo: it.texto, inicio: Date.now() + 3600000, lembretes: [0] })
  if (r.err) return estado('não foi para a Agenda: ' + r.err, 'erro')
  await App.notificar('Lembrete na Agenda', it.texto + ' (daqui a 1 h)')
  estado('na Agenda', true)
}
document.getElementById('novo').onsubmit = e => {
  e.preventDefault()
  const t = document.getElementById('texto').value.trim()
  if (!t) return
  itens.unshift({ texto: t, em: Date.now() })
  document.getElementById('texto').value = ''
  desenhar(); salvar()
}
carregar()
</script>
</body>
</html>

<script src="/app.js"> vem logo depois de <body>. App.dados, App.colecao e App.api nunca lançam erro: devolvem um objeto com err quando falham. O mesmo app abre no celular: nada de hover obrigatório.

Empacote, instale e abra

O pacote é a pasta num .tar.gz com o manifesto na raiz (sem links, até 30 MB):

tar czf lembretes-rapidos-0.1.0.tar.gz -C lembretes-rapidos .
curl -s -X POST -H "x-spaceman-token: $TK" -H 'content-type: application/gzip' \
  --data-binary @lembretes-rapidos-0.1.0.tar.gz $H/app-instalar
# {"ok":true,"id":"lembretes-rapidos","versao":"0.1.0","capacidades":["eventos:escrever","notificar"]}
curl -s -X POST -H "x-spaceman-token: $TK" -H 'content-type: application/json' $H/abrir \
  --data '{"id":"lembretes-rapidos","page":"Teste","x":40,"y":40}'

Ou a pessoa instala sem dar acesso ao agente: Loja → Instalados → Instalar de um arquivo. Para atualizar, suba versao e instale de novo (os dados ficam). Para remover: POST /app-remover {"id":"lembretes-rapidos"}.

Teste

Abra http://127.0.0.1:17400/a/lembretes-rapidos/?janela=1 (num hub fechado, o navegador precisa estar pareado) e confira:

  • sem erro no console, e App.isolado é true;
  • grave e recarregue: o dado volta (GET /app-dados/lembretes-rapidos/itens);
  • cada capacidade funciona: o compromisso aparece em GET /colecoes/eventos com origem.id do app, e o aviso em GET /notificacoes;
  • a tela funciona com 360 px de largura e com a janela grande.

Armadilhas do isolamento: localStorage, sessionStorage e cookies dão SecurityError (use App.dados); fetch direto às rotas do hub falha (use App.*); capacidade não declarada devolve err; arquivos do app são públicos para quem alcança o hub, então nada de segredo no código.

Entregue

Mande o .tar.gz, a pasta-fonte e uma linha dizendo o que o app faz e por que pede cada capacidade. Para entrar na loja pública, envie o pacote à DYNAMI.art (veja Publicar na loja).

Manifesto

spaceman-app.yaml (ou spaceman-app.json com os mesmos campos).

CampoO que é
idIdentificador único; vira o endereço /a/<id>/.
nome, descricao, autorO que a loja e o launcher mostram.
versaomajor.minor.ciclo. A loja oferece a atualização quando muda.
entradaPágina inicial (padrão index.html).
icone, imagemEmoji curto (celular e relógio usam este) e imagem do mosaico.
janelaTamanho ao abrir: {w, h}.
estado, tituloParâmetros que ficam na URL da janela (o documento aberto, por exemplo) e o título com eles: "Esboço · {doc}".
capacidadesPermissões que o app pede (veja abaixo). A pessoa confirma ao instalar.
urlSó para apps site: o endereço da página, que mora no seu servidor.
webEndereço onde o app também roda fora do Space (aparece como Abrir na web na loja).
substituiOcupa um lugar do sistema, como internet (navegador) ou sessoes.

A interface App

<script src="/app.js"> logo depois de <body> deixa pronto o objeto App. App.versao só muda quando algo deixar de funcionar como está aqui.

ChamadaO que faz
App.dados.ler(chave) · gravar(chave, obj) · listar() · apagar(chave)Documentos JSON do app (até 4 MB cada), os mesmos em todos os aparelhos.
App.salvarEstado({ chave: valor })Guarda o estado na URL da janela: reabrir ou abrir em outro aparelho volta igual.
App.abrir(id, extra?)Abre outro item do catálogo como janela ao lado desta.
App.notificar(titulo, texto, nivel?)Aviso em todos os aparelhos (relógio vibra). nivel: info, pendente, pronto, erro.
App.armazenamento.*Arquivos de pen drives e discos das máquinas da pessoa (veja Arquivos das mídias).
App.estado(texto, tipo)Mensagem na barra da janela.
App.repetir(fn, ms)Repete com recuo até 30 s quando fn devolve false.
App.QS, App.appId, App.toqueParâmetros da URL, id do app e se a tela é de toque.

/app.css traz a barra padrão (.bar, .btitle, #st) para o app combinar com o resto do Space.

Capacidades e isolamento

Todo app roda isolado: sem cookies nem armazenamento do navegador do Space, falando só pelo token dele. O que ele pode fazer além dos próprios dados vem das capacidades que declarou.

CapacidadeDá acesso a
abrirAbrir janelas do catálogo.
sessoesListar os tipos de sessão (emuladores, máquinas virtuais).
armazenamentoPedir arquivos das mídias das máquinas e abri-los no visor.
notificarMandar avisos a todos os aparelhos.

Os próprios dados (App.dados) não pedem capacidade. Capacidades de alto impacto, como terminal, são explicadas à pessoa antes de instalar; nenhuma dá os dados de outro app. No app isolado, localStorage, sessionStorage e cookies não funcionam: use App.dados.

Dados da pessoa

Alguns dados são da pessoa, não de um app: a agenda, os timers. Eles ficam em coleções no Space dela, e vários apps usam a mesma, cada um com a sua permissão. Um compromisso criado pelo seu app aparece na Agenda do Space "via" ele, e o lembrete toca em todos os aparelhos.

# spaceman-app.yaml
capacidades: [eventos:escrever, timers:escrever]
const agenda = App.colecao('eventos')
await agenda.criar({ titulo: 'Entrega do card', inicio: '2026-10-24T15:00', lembretes: [30], link: location.href })
App.colecao('timers').criar({ titulo: 'Foco', duracao: 25 * 60000 })   // toca no relógio, celular e computador
agenda.ouvir(({ itens }) => desenhar(itens))                // só o que mudou, sempre atualizado
PermissãoPode
<coleção>:lerler tudo da coleção
<coleção>:escreverler, criar, e mudar ou apagar só o que o seu app criou
<coleção>:gerirtudo (reservado a apps como a própria Agenda)

Coleções hoje: eventos (agenda) e timers. Em apps site, as mesmas operações vêm pela ponte: colecao.criar, colecao.listar, colecao.atualizar, colecao.apagar.

Arquivos das mídias

Com armazenamento, o app pede um arquivo pelo identificador da mídia e pelo caminho dentro dela. A pessoa autoriza, o Space espera a mídia ser conectada em qualquer máquina dela e abre o arquivo no visor.

const p = await App.armazenamento.pedir({
  volume: 'usb:50026B7782D55D66',   // serial do disco (ou :part2, ou UUID do sistema de arquivos)
  caminho: 'videos/2020/viagem.mp4',  // relativo à raiz da mídia
  tamanho: 48230112,                  // confere que é o arquivo certo
  midia: 'Pen drive azul',            // nome no aviso
  objetivo: 'Mostrar o vídeo que você escolheu'   // o que a pessoa lê para autorizar
})
await App.armazenamento.ver(p.id)        // abre o visor: a pessoa autoriza e o vídeo toca quando a mídia aparecer
A pessoa sempre autoriza. Cada pedido de arquivo de um app nasce esperando a decisão dela, numa tela do próprio Space (o visor Arquivos), que mostra o seu app, o arquivo, a mídia, o tamanho e o objetivo que você informou. O app nunca vê nem aciona essa tela, e nenhum byte sai antes do sim. Cada decisão fica registrada (quem, de qual aparelho, quando).

Informe sempre um objetivo curto e verdadeiro ('Mostrar o vídeo que você escolheu'): é o que a pessoa lê para decidir. O pedido passa por autorizar → aguardando (a mídia) → pronto, ou recusado, ou erro se o tamanho não bate. Se a mídia sai, ele volta a aguardar. Pedir o mesmo arquivo de novo depois de decidido gera um pedido novo, com nova autorização. Também há volumes(), pedidos(), pedido(id) e cancelar(id).

Apps site

Já tem um site? Ele vira app do Space sem mudar de endereço. O pacote tem só o manifesto com url; o Space abre o site numa janela e conversa com ele por postMessage, com as mesmas capacidades.

id: meu-site
nome: Meu site
versao: 0.1.0
url: https://meusite.exemplo/
capacidades: [notificar, armazenamento]

No site, um cliente pequeno basta. Ele só liga quando a página está dentro do Space; fora dele, nada muda.

let origem = null, n = 0
const espera = new Map()
addEventListener('message', e => {
  const m = e.data
  if (e.source !== parent || m?.spaceman !== 1) return
  if (m.evento === 'pronto') { origem = e.origin; return }   // estamos no Space
  const w = espera.get(m.id); if (!w) return
  espera.delete(m.id); m.ok ? w.ok(m.resultado) : w.falha(new Error(m.err))
})
const space = (op, args) => new Promise((ok, falha) => {
  const id = ++n; espera.set(id, { ok, falha })
  parent.postMessage({ spaceman: 1, id, op, args }, origem)
})
// space('notificar', { titulo: 'Pronto', texto: 'Relatório gerado' })

Operações: info, rota (guarda o caminho do site na janela), dados.listar|ler|gravar|apagar, notificar, abrir e armazenamento.volumes|pedir|pedidos|pedido|cancelar|ver. O Space também avisa com { evento: 'pedido', pedido } quando um arquivo pedido fica pronto.

O site nunca recebe credenciais do Space: a janela fala por ele, só com as capacidades do manifesto.

Rodar também na web

Se a página não depende do Space, ela pode ficar num endereço público. Declare web: https://… no manifesto e a loja mostra Abrir na web. Na página, trate a ausência do Space:

const noSpace = typeof App !== 'undefined' && App.appId
const guardar = (k, v) => noSpace ? App.dados.gravar(k, v) : localStorage.setItem(k, JSON.stringify(v))

Publicar na loja

A loja lê um catálogo aberto (catalogo.json). Para publicar, o pacote é gerado com os arquivos versionados no git do app, conferido por SHA-256 e entra no catálogo; o Spaceman de cada pessoa instala e atualiza por ele, em Configurações → Apps.

O acesso ao console de desenvolvimento é exclusivo da equipe do Space. Entre com e-mail e senha; se precisar, use a opção Esqueci minha senha.

Na sua conta de desenvolvimento, informe o repositório, o commit, a versão e a documentação do projeto. Relacione cada tela e funcionalidade ao código, aos passos de teste e ao resultado esperado. Os testes geram capturas em computador e celular no ambiente de homologação autorizado pelo Space.

Inclua as notas de submissão do novo app ou as notas de alteração da nova versão. Nosso agente usa essas notas para ler o código, navegar pelos fluxos e tirar suas próprias capturas. A submissão só segue quando a IA qualificar a entrega de ponta a ponta e validar todos os itens da checklist.

Depois da qualificação por IA, envie a revisão ao staff. Cada item pode ser aprovado ou receber um pedido de modificação com comentários; integrantes autorizados da equipe podem acompanhar e responder. Alterações no projeto exigem uma nova revisão. A publicação só aceita o pacote cujo SHA-256 recebeu qualificação e aprovação.

Exemplos

Esboço 3D

Desenho à mão livre no espaço 3D. App comum que também roda na web.

Ver na loja ↗

Eletrônica

Circuitos e displays com MicroPython, como janela do Space.

Ver na loja ↗

Organizr

App site: busca em todas as máquinas e abre arquivos de pen drives pelo Space.

Ver na loja ↗