Your AI sessions keep running when the laptop closes, on a machine you own, with backups, alerts on your phone and a place for your second brain.
Suas sessões de IA continuam rodando quando o notebook fecha, numa máquina sua, com backup, avisos no celular e um lugar para o seu second brain.
curl -fsSL https://raw.githubusercontent.com/ogabrielalonso/personal-server-kit/main/install.sh | bash
One question at a time, then each step checks, acts and proves. If a step fails, you get one sentence, a next action and a diagnostic file; running it again resumes where it stopped.Uma pergunta por vez, e cada passo confere, age e prova. Se um passo falhar, você recebe uma frase, a próxima ação e um arquivo de diagnóstico; rodar de novo continua de onde parou.
$ curl -fsSL https://raw.githubusercontent.com/.../install.sh | bash Language / Idioma [1] English (default) [2] Português Choose 1-2 (Enter for default): (Enter) personal-server-kit 0.2.0 ------------------------- What is this computer? [1] My always-on server (this Linux machine) (default) [2] My computer: connect it to a server I already set up Choose 1-2 (Enter for default): 1 ... [1/20] Your user account ok already in place ... [12/20] Private network (Tailscale) ok done ... [15/20] Encrypted backup Running the first backup and a restore test... ok Backup works: 12 files restored and compared. ... [17/20] Connect your laptop +----------------------------------------------------------------+ | Now connect your laptop to this server. | | | | On your laptop, open a terminal and run: | | curl -fsSL .../install.sh | bash | | Choose 'connect it to a server' and enter: | | | | Server address: 100.64.0.7 | | Pairing code: K7QX-M4RW | | | | The laptop needs Tailscale too, signed in to the same account. | +----------------------------------------------------------------+ Waiting for the laptop (15 min left)..._
$ curl -fsSL https://raw.githubusercontent.com/.../install.sh | bash Language / Idioma [1] English (default) [2] Português Choose 1-2 (Enter for default): 2 personal-server-kit 0.2.0 ------------------------- O que é este computador? [1] Meu servidor sempre ligado (esta máquina Linux) (padrão) [2] Meu computador: conectar a um servidor que já configurei Escolha 1-2 (Enter para o padrão): 1 ... [1/20] Sua conta de usuário ok já estava pronto ... [12/20] Rede privada (Tailscale) ok feito ... [15/20] Backup criptografado Rodando o primeiro backup e um teste de restauração... ok O backup funciona: 12 arquivos restaurados e comparados. ... [17/20] Conectar seu laptop +-------------------------------------------------------+ | Agora conecte seu laptop a este servidor. | | | | No laptop, abra um terminal e rode: | | curl -fsSL .../install.sh | bash | | Escolha 'conectar a um servidor' e informe: | | | | Endereço do servidor: 100.64.0.7 | | Código de pareamento: K7QX-M4RW | | | | O laptop também precisa do Tailscale, na mesma conta. | +-------------------------------------------------------+ Aguardando o laptop (faltam 15 min)..._
For anyone who has never set up a server. No jargon in this part; every technical detail is further down the page, for whoever wants it.
Para quem nunca montou um servidor. Esta parte não tem termo técnico; os detalhes ficam mais abaixo na página, para quem quiser.
An installer that turns an always-on Linux computer into your own server for AI work. It applies and checks the dozens of settings a system administrator would otherwise make by hand, so you do not need to be one.
Um instalador que transforma um computador Linux sempre ligado no seu servidor pessoal para trabalhar com IA. Ele aplica e confere as dezenas de ajustes que um administrador de sistemas faria à mão, então você não precisa ser um.
People who work with AI assistants that act directly on files, such as Claude Code or Codex, and want them running somewhere that stays on when the laptop closes. If you only use AI in the browser, you do not need this yet.
Quem trabalha com assistentes de IA que mexem direto nos arquivos, como Claude Code ou Codex, e quer que eles rodem num lugar que continua ligado quando o notebook fecha. Se você só usa IA pelo navegador, ainda não precisa disto.
A server closed to the internet and open only to your own devices, an encrypted backup that is tested every week, alerts on your phone only when something needs you, and a machine that comes back by itself after a restart.
Um servidor fechado para a internet e aberto só para os seus aparelhos, um backup criptografado testado toda semana, avisos no celular só quando algo precisa de você e uma máquina que volta sozinha depois de reiniciar.
An unfamiliar word? The glossary near the end explains each one in plain words.
Alguma palavra estranha? O glossário perto do fim explica cada uma em palavras simples.
Five steps, from an empty machine to a server that looks after itself. The installer does everything else; on a test machine the whole install took under 10 minutes, not counting creating the accounts.
Cinco passos, de uma máquina vazia a um servidor que se cuida sozinho. O resto é com o instalador; numa máquina de teste, a instalação inteira levou menos de 10 minutos, sem contar a criação das contas.
Rent a small cloud server (a VPS) or use an old PC with Ubuntu 24.04. It is the one that stays on.
Alugue um servidor pequeno na nuvem (um VPS) ou use um PC antigo com Ubuntu 24.04. É ele que vai ficar ligado.
Open the machine's terminal: on a rented server, through the provider's web console or the login it gives you; on a PC, through its Terminal app. Paste the line at the top of this page; the first question is the language.
Abra o terminal da máquina: num servidor alugado, pelo console no site do provedor ou pelo acesso que ele te passa; num PC, pelo app Terminal. Cole a linha do topo desta página; a primeira pergunta é o idioma.
$ curl -fsSL …/install.sh | bashServer name, time zone, where alerts go and where the backup lives. Nothing changes until it has checked the machine and shown you a summary.
Nome do servidor, fuso horário, para onde vão os avisos e onde fica o backup. Nada muda antes de ele conferir a máquina e mostrar um resumo.
The server shows its address on your private network and an 8 character code. On the laptop you run the same command (the installer also sets up laptops), choose to connect to a server and type both.
O servidor mostra o endereço dele na sua rede privada e um código de 8 caracteres. No notebook, você roda o mesmo comando (o instalador também prepara notebooks), escolhe conectar a um servidor e digita os dois.
The server closes itself to the internet, restarts to prove everything comes back, and sends the result to your phone.
O servidor se fecha para a internet, reinicia para provar que tudo volta e manda o resultado para o seu celular.
If a step fails, the installer stops, says in one sentence what happened and what to do, and picks up where it stopped when you run it again. If you change your mind, one command undoes what the kit installed and keeps your data.
That is enough to decide. The sections below explain each part in more depth: why each rule exists, how the install works, the security and the proof.
Se um passo falhar, o instalador para, diz em uma frase o que aconteceu e o que fazer, e continua de onde parou quando você rodar de novo. E se mudar de ideia, um comando desfaz o que o kit instalou e mantém os seus dados.
Isso é o essencial para decidir. As seções abaixo explicam cada parte com mais detalhe: por que cada regra existe, como a instalação funciona, a segurança e as provas.
A server that stays on day and night tends to break for the same few reasons: the disk fills up, memory runs out, remote access does not come back after a restart, and alerts turn into noise nobody reads. The kit ships a ready rule for each one. On the right, the first sentence says what you get; the rest is the technical detail.
Um servidor que fica ligado dia e noite costuma quebrar sempre pelos mesmos motivos: o disco enche, a memória acaba, o acesso não volta depois de reiniciar, e os avisos viram barulho que ninguém lê. O kit traz uma regra pronta para cada um. À direita, a primeira frase diz o que você ganha; o resto é o detalhe técnico.
After a restart, remote access sometimes never comes back, for example when a second access service starts before the network is ready.
Depois de reiniciar, o acesso remoto às vezes não volta, por exemplo quando um segundo serviço de acesso sobe antes de a rede estar pronta.
Remote access always comes back after a restart.
O acesso remoto sempre volta depois de reiniciar.
One standard sshd, filtered by the firewall instead of bound to the tailnet; /run/sshd created at every boot; the install ends with a real reboot.
Um único sshd padrão, filtrado pelo firewall em vez de preso ao IP da tailnet; /run/sshd criado a cada boot; a instalação termina com um reboot de verdade.
lockdown.py · prove.pyA device that silently stops sending its sessions can go unnoticed for days.
Um dispositivo que para de enviar suas sessões em silêncio pode passar dias sem ninguém perceber.
You find out when a device stops sending.
Você fica sabendo quando um aparelho para de enviar.
Every device leaves a delivery receipt; three silent days show up in the daily summary.
Cada dispositivo deixa um recibo de entrega; três dias de silêncio aparecem no resumo diário.
bridge.py · checks.pyForgotten temporary files and AI assistants' histories, which only grow, fill the main disk.
Arquivos temporários esquecidos e históricos dos assistentes de IA, que só crescem, enchem o disco principal.
The disk does not fill up with leftovers.
O disco não enche com sobras.
/tmp cleaned after 10 days, orphan browsers and dev servers reaped, agent histories reported daily and never deleted.
/tmp limpo após 10 dias, navegadores e dev servers órfãos encerrados, históricos de agentes reportados todo dia e nunca apagados.
tmpfiles · runtime/reaper.pyMemory limits set one by one can add up to more than the machine has, leaving nothing to protect the system.
Limites de memória definidos um a um podem somar mais do que a máquina tem, sem sobrar nada para proteger o sistema.
Memory is never promised beyond what the machine has.
A memória nunca é prometida além do que a máquina tem.
Limits computed from the machine's RAM; their sum always stays below it, with a margin for the kernel.
Limites calculados a partir da RAM da máquina; a soma sempre fica abaixo dela, com margem para o kernel.
budget.pyAn alert that fires on every check repeats all day while disk usage hovers near the threshold.
Um alerta que dispara a cada verificação se repete o dia todo enquanto o uso do disco oscila perto do limite.
Few alerts, and only the ones that matter.
Poucos avisos, e só os que importam.
One stable key per problem, a margin to clear it, one message when it starts, changes or clears, a reminder once a day.
Uma chave estável por problema, margem para sair do alerta, uma mensagem quando começa, muda ou termina, e um lembrete por dia.
alerts.py · notify.pyBackups sent to a laptop fail whenever the laptop is asleep.
Backups enviados para um laptop falham sempre que ele está dormindo.
The backup never depends on a laptop being on, and it is tested.
O backup nunca depende de um notebook ligado, e é testado.
No default destination depends on a laptop; an evening retry; a weekly restore test compared by hash.
Nenhum destino padrão depende de laptop; nova tentativa à noite; teste de restauração semanal comparado por hash.
setup_backup.py · runtime/backup.pyWhen two tools manage the same services, each one undoes the other's changes.
Quando duas ferramentas gerenciam os mesmos serviços, uma desfaz as mudanças da outra.
Only one tool manages the server's services.
Só uma ferramenta cuida dos serviços do servidor.
The host installs every unit. The brain only declares what it needs, in a manifest.
O host instala todas as units. O brain só declara o que precisa, num manifesto.
manifest.py · brainslot.pyThe second question the installer asks is what this computer is. Each answer runs a different scenario. The server runs Linux on any machine the owner already has; the laptop can be a Mac or a Linux machine.
A segunda pergunta do instalador é o que este computador é. Cada resposta roda um cenário diferente. O servidor roda Linux em qualquer máquina que o dono já tenha; o laptop pode ser um Mac ou uma máquina Linux.
A rented VPS or an old PC with Ubuntu 24.04. The reference scenario.
Um VPS alugado ou um PC antigo com Ubuntu 24.04. O cenário de referência.
Connects the owner's laptop to a server with a pairing code shown on the server's screen.
Conecta o laptop do dono a um servidor com um código de pareamento que aparece na tela do servidor.
No server at all. The installer says so plainly and hands off to the brain kit on the laptop.
Nenhum servidor. O instalador diz isso com clareza e passa a vez para o kit do brain no laptop.
Think of the server as a house with a single door that opens only for your own devices: the laptop and the server talk over a private network, and nothing on the server is exposed to the internet. The kit looks after the house (access, memory, alerts, backup); the second brain lives in a room the kit prepares for it, with written rules about what each side may do.
Pense no servidor como uma casa com uma única porta, que só abre para os seus aparelhos: o notebook e o servidor conversam por uma rede privada, e nada no servidor fica exposto à internet. O kit cuida da casa (acesso, memória, avisos, backup); o second brain mora num quarto que o kit prepara para ele, com regras escritas sobre o que cada lado pode fazer.
It was written for people who are not system administrators. The questions are plain; when something blocks, you get one sentence and the next thing to do; and a machine is never left half configured. Nothing changes until the pre-check passes.
Foi escrito para quem não é administrador de sistemas. As perguntas são simples; quando algo bloqueia, você recebe uma frase e a próxima ação; e nenhuma máquina fica configurada pela metade. Nada muda antes da pré-checagem passar.
Run it again and it continues where it stopped. Finished steps are re-checked against the real machine, never blindly re-applied.
Rode de novo e ele continua de onde parou. Passos concluídos são reconferidos na máquina real, nunca reaplicados às cegas.
Every change is written down in a log (the ledger). pskit uninstall undoes it and keeps your data; files you edited afterwards are left alone.
Toda mudança fica anotada num registro (o ledger). pskit uninstall desfaz tudo e mantém seus dados; arquivos que você editou depois ficam como estão.
Closing public access is armed with a 10-minute automatic undo that also survives a reboot.
Fechar o acesso público é armado com um desfazer automático de 10 minutos que sobrevive até a um reboot.
When a step fails you get its path. Tokens, keys, passwords, ping URLs and public addresses are redacted.
Quando um passo falha, você recebe o caminho dele. Tokens, chaves, senhas, URLs de ping e endereços públicos saem apagados.
Every question has a key in an answers file. Secrets never go there; they come from environment variables.
Toda pergunta tem uma chave num arquivo de respostas. Segredos nunca vão nele; vêm de variáveis de ambiente.
Closing the server to the internet is the only step that could lock you out, so it is never done blindly. The kit saves how things were, arms an automatic undo of 10 minutes, closes the door and waits for your laptop to prove it can still get in. If it cannot, everything goes back on its own.
Fechar o servidor para a internet é o único passo que poderia deixar você do lado de fora, então ele nunca é feito às cegas. O kit guarda como estava, arma um desfazer automático de 10 minutos, fecha a porta e espera o seu notebook provar que ainda consegue entrar. Se não conseguir, tudo volta sozinho.
Example code. Its alphabet leaves out the characters people confuse:
Código de exemplo. O alfabeto deixa de fora os caracteres que as pessoas confundem:
0 1 2 3 4 5 6 7 8 9 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Technical detail, found while testing: restrict alone does not stop a key from running commands, and adding port-forwarding also re-enables remote listens. Hence command= and permitlisten, both proven on a real sshd. A lost laptop is revoked with sudo pskit forget-device <name>: all three keys at once.
Detalhe técnico, descoberto nos testes: restrict sozinho não impede uma chave de rodar comandos, e adicionar port-forwarding reabilita escutas remotas. Por isso o command= e o permitlisten, os dois comprovados num sshd real. Um laptop perdido é revogado com sudo pskit forget-device <nome>: as três chaves de uma vez.
log in as the owner and use sudo with your password
entrar como o dono e usar sudo com a sua senha
passwords off for SSH, root login off, only the owner allowed
senha desligada no SSH, login root desligado, só o dono permitido
restrict,port-forwarding,permitopen="127.0.0.1:8799",permitlisten="127.0.0.1:1",command="/usr/bin/false"
carry the laptop's 127.0.0.1:8799 to the brain's port
levar o 127.0.0.1:8799 do laptop até a porta do brain
run commands, reach other ports, or open a way back into the server
rodar comandos, alcançar outras portas ou abrir um caminho de volta para dentro do servidor
restrict,command="/usr/local/bin/pskit bridge-receive --device <name>"
deliver session files into its own device folder
entregar arquivos de sessão na pasta do próprio dispositivo
open a shell, forward ports, or write anywhere else
abrir um shell, encaminhar portas ou escrever em outro lugar
Nothing listens publicly; keys only, owner only.
Nada escuta em público; só chave, só o dono.
Two of the three keys cannot open a shell; one command revokes all.
Duas das três chaves não abrem shell; um comando revoga todas.
Host keys pinned at pairing, strict checking on.
Chaves do host fixadas no pareamento, checagem estrita ligada.
Own user; read-only system and no homes; writes only to its home, the spool and the lock.
Usuário próprio; sistema somente leitura e sem acesso às homes; escreve só na sua casa, no spool e na trava.
Only root delivers alerts; the token lives in a root-only folder.
Só o root entrega alertas; o token fica numa pasta só do root.
Known agent trees only; no .., no symlinks; headers validated; atomic writes.
Só as árvores conhecidas dos agentes; sem .., sem symlinks; cabeçalhos validados; escrita atômica.
Tailscale from its signed repository; restic checked against its SHA-256.
Tailscale do repositório assinado; restic conferido pelo SHA-256.
The diagnostic file lists secret files, never their content.
O diagnóstico lista os arquivos secretos, nunca o conteúdo.
A compromised Tailscale account (use 2FA), a compromised owner account, the VPS provider's access to the live disk, and Tailscale key expiry if left on.
Uma conta Tailscale comprometida (use 2FA), a conta do dono comprometida, o acesso do provedor do VPS ao disco em uso e a expiração da chave do Tailscale, se ficar ligada.
Every working conversation with an AI assistant (Claude Code, Codex or Grok) is saved as a file. The kit gathers these files from the laptop and from the server itself into one place, for the second brain to read. The brain never reads anyone's personal folder, and if a device stops sending, you hear about it within three days, not weeks later.
Cada conversa de trabalho com um assistente de IA (Claude Code, Codex ou Grok) fica guardada num arquivo. O kit junta esses arquivos do notebook e do próprio servidor num único lugar, para o second brain ler. O brain nunca lê a pasta pessoal de ninguém, e se um aparelho parar de enviar, você fica sabendo em até três dias, não semanas depois.
Technical detailDetalhe técnico
Once installed, the server keeps its own memory in order, cleans up after agents, backs itself up, proves the backup works, and reaches your phone when something needs you.
Depois de instalado, o servidor mantém a própria memória em ordem, limpa o que os agentes deixam para trás, faz o próprio backup, prova que o backup funciona e chega no seu celular quando algo precisa de você.
| Group (slice)Grupo (slice) | ProtectedProtegido | Slowed fromFreado a partir de | Hard ceilingTeto duro |
|---|---|---|---|
brain pskit-brain.slice | 4 GiB | 8 GiB | 10 GiB |
your sessionssuas sessões user-UID.slice | 0 | 12.25 GiB | 14.25 GiB |
CI pskit-ci.slice | 0 | 3 GiB | 4 GiB |
systemsistema system.slice | 2 GiB | - | - |
A guard checks every 30 seconds; six bad checks in a row freeze the brain and CI (never kill them), two good ones thaw them, and no freeze lasts more than 30 minutes.
Um guarda verifica a cada 30 segundos; seis verificações ruins seguidas congelam o brain e o CI (nunca matam), duas boas descongelam, e nenhum congelamento passa de 30 minutos.
Illustration on an example curve. The kit's lane follows the real rule in alerts.py: a level starts at its threshold and ends only 5 points below it. A naive rule, with no margin and a key that changes with the level, sends a new alert every time usage crosses 80%.
Ilustração numa curva de exemplo. A linha do kit segue a regra real do alerts.py: um nível começa no limite e só termina 5 pontos abaixo dele. Uma regra ingênua, sem margem e com a chave mudando junto com o nível, manda um alerta novo toda vez que o uso cruza os 80%.
The private network is down, SSH is not listening, the firewall is off, disk above 90%.
A rede privada caiu, o SSH não está escutando, o firewall está desligado, disco acima de 90%.
A failed unit, a stale backup, the brain not answering, disk above 80%. Reminded once a day while it lasts.
Uma unit com falha, backup atrasado, o brain sem responder, disco acima de 80%. Lembrado uma vez por dia enquanto durar.
Open problems, disk use, the last backup, a pending reboot, agent history sizes and devices silent for 3 days. One message a day.
Problemas abertos, uso de disco, último backup, reboot pendente, tamanho dos históricos dos agentes e dispositivos em silêncio há 3 dias. Uma mensagem por dia.
Anyone in the pskit group, including the brain, alerts with pskit notify warn "title" --key K. The message goes into a spool; only root delivers it, so the Telegram token or ntfy topic never leaves the root-only secrets folder.
Qualquer membro do grupo pskit, inclusive o brain, alerta com pskit notify warn "título" --key K. A mensagem vai para um spool; só o root entrega, então o token do Telegram ou o tópico do ntfy nunca sai da pasta de segredos do root.
Outer dotted ring: every 5 minutes. Inner ring: every 15 minutes. Hollow marks: weekly or only when needed.
Anel pontilhado externo: a cada 5 minutos. Anel interno: a cada 15 minutos. Marcas vazadas: semanal ou só quando preciso.
restic keeps 7 daily, 4 weekly and 6 monthly snapshots; old data pruned on Sundays.
O restic mantém 7 snapshots diários, 4 semanais e 6 mensais; dados antigos podados aos domingos.
Conservative pip and npm cache maintenance.
Manutenção conservadora dos caches de pip e npm.
Everything that did not deserve an interruption.
Tudo o que não merecia uma interrupção.
Only when there has been no success for 18 hours.
Só quando não há sucesso há 18 horas.
Restores a sample and compares it by hash, under the heavy-job lock.
Restaura uma amostra e compara por hash, sob a trava de jobs pesados.
Freezes brain and CI when the machine stops responding.
Congela brain e CI quando a máquina para de responder.
Disk, memory, network, units, backup age, brain health; a ping to the outside watcher.
Disco, memória, rede, units, idade do backup, saúde do brain; um ping para o vigia externo.
Ends headless browsers older than 3 h and idle dev servers older than 12 h.
Encerra navegadores headless com mais de 3 h e dev servers ociosos com mais de 12 h.
Times from the example manifest; the brain chooses its own.
Horários do manifesto de exemplo; o brain escolhe os seus.
pskit statusshort summaryresumo curtopskit doctorevery check in plain languagetodas as verificações em linguagem simplespskit doctor --bundlediagnostic file, no secretsarquivo de diagnóstico, sem segredospskit doctor --auditread-only, on any Ubuntu machinesó leitura, em qualquer Ubuntusudo pskit pair-serveaccept one more laptopaceitar mais um laptopsudo pskit forget-device NAMErevoke a lost or replaced laptoprevogar um laptop perdido ou trocado./install.shon the laptop: choose 'connect it to a server'no laptop: escolha 'conectar a um servidor'sudo pskit brain validate FILEcheck a manifestconferir um manifestosudo pskit brain apply FILEinstall its servicesinstalar os serviços delepskit notify SEV TITLEalert the owneralertar o donosudo pskit backup runback up nowfazer backup agorasudo pskit backup restore-testprove a restore nowprovar uma restauração agorasudo pskit backup snapshotslist what is storedlistar o que está guardadosudo pskit provereboot proof on demandprova de reboot quando quiserpskit prove --statuslast proof resultresultado da última provasudo pskit uninstallundo everything from the ledger; data keptdesfaz tudo pelo ledger; dados mantidosWhat the kit promises was checked in four ways: automated tests, a full install on a throwaway test machine, a real run the way a person would do it, and reviews by a different AI model. Whoever built it did not check their own work, and what is not proven yet is listed just as plainly.
O que o kit promete foi conferido de quatro jeitos: testes automáticos, uma instalação completa numa máquina de teste descartável, uma execução de verdade como uma pessoa faria e revisões feitas por outro modelo de IA. Quem construiu não conferiu o próprio trabalho, e o que ainda não foi provado está listado com a mesma clareza.
A scripted command runner stands in for the system; pairing runs over real HTTP on loopback; both languages must have every message.
Um executor de comandos roteirizado faz o papel do sistema; o pareamento roda por HTTP real no loopback; as duas línguas precisam ter todas as mensagens.
Plus Python 3.9 in the matrix, because that is what macOS ships.
Mais o Python 3.9 na matriz, porque é o que o macOS traz.
Packages, slices with real ceilings, firewall and key-only SSH, a restic backup and restore test, a fake brain from a manifest, a second user paired as the laptop over real SSH, a second run that changes nothing, and uninstall.
Pacotes, slices com tetos reais, firewall e SSH só com chave, backup e teste de restauração com restic, um brain falso a partir de um manifesto, um segundo usuário pareado como laptop por SSH real, uma segunda execução que não muda nada e a desinstalação.
One server and two laptops from the Ubuntu cloud image, run as a person would: real Tailscale, Telegram alerts, an SFTP backup to another machine with the restore test, two pairings, the lockdown checked from outside.
Um servidor e dois laptops a partir da imagem cloud do Ubuntu, rodados como uma pessoa rodaria: Tailscale real, alertas no Telegram, backup por SFTP para outra máquina com o teste de restauração, dois pareamentos, o lockdown conferido de fora.
Each fix counted only after a new test was shown to fail on the previous code. Examples from round 1: uninstall could restore an old /etc/fstab over later edits; the lockdown's undo was armed after the changes; root followed symlinks in the alert spool. The VM also caught the /run/sshd reboot defect behind the SSH rule. The real VM run caught the worst one: on a server up for more than ten minutes, the lockdown undid itself seconds after it was applied.
Cada correção só contou depois que um teste novo falhou no código anterior. Exemplos da rodada 1: a desinstalação podia restaurar um /etc/fstab antigo por cima de edições posteriores; o desfazer do lockdown era armado depois das mudanças; o root seguia symlinks no spool de alertas. A VM também detectou o defeito do /run/sshd no reboot, o que está por trás da regra de SSH. A rodada em VMs reais pegou o pior deles: num servidor ligado havia mais de dez minutos, o lockdown se desfazia segundos depois de aplicado.
| Gap | Lacuna | Why | Por quê | How it closes | Como fecha |
|---|---|---|---|---|---|
| A rented VPS | Um VPS alugado | The real run used plain virtual machines; a provider's image, network and console were not exercised | A execução real usou máquinas virtuais simples; imagem, rede e console de um provedor não foram exercitados | One install on a small hourly VPS | Uma instalação num VPS pequeno por hora |
| Real Tailscale in CI | Tailscale real no CI | CI skips it and pairs over loopback; the real VM run covered it by hand | O CI pula e pareia pelo loopback; a execução em VMs reais cobriu à mão | An auth key stored as a CI secret | Uma auth key guardada como segredo do CI |
| Laptop side on macOS | Lado do laptop no macOS | launchd agents and macOS openssh are unit tested only; the Linux laptop side ran for real | Agentes launchd e o openssh do macOS só têm teste unitário; o lado do laptop Linux rodou de verdade | The first real pairing from a Mac | O primeiro pareamento real a partir de um Mac |
| ntfy delivery | Entrega por ntfy | Covered with fake HTTP endpoints; Telegram ran for real | Coberta com endpoints HTTP falsos; o Telegram rodou de verdade | The first real install with ntfy | A primeira instalação real com ntfy |
| Long-running behavior | Comportamento de longo prazo | Reminders, weekly restore tests, freezes under real load | Lembretes, testes de restauração semanais, congelamentos sob carga real | Weeks of real use | Semanas de uso real |
Each term in a sentence or two, in plain words.
Cada termo em uma ou duas frases, em palavras simples.
The rest of the page is for people who want to build on the kit: the written contract between the server and the second brain, and what is inside the repository.
O restante da página é para quem quer construir em cima do kit: o contrato escrito entre o servidor e o second brain, e o que tem dentro do repositório.
The host never reaches into the brain, and the brain never configures the machine. Each side can change anything behind its half; changing the contract needs both. Most breakages happen where the two get mixed.
O host nunca mexe no interior do brain, e o brain nunca configura a máquina. Cada lado pode mudar o que quiser da sua metade; mudar o contrato exige os dois. A maioria das quebras acontece onde os dois se misturam.
pskit-brain; the owner is in the group and reads everything.Uma identidade: usuário e grupo pskit-brain; o dono está no grupo e lê tudo.brain_home, the only place the brain writes; disk use watched.Uma casa: brain_home, o único lugar onde o brain escreve; uso de disco vigiado.pskit notify, without ever seeing the channel's credential.Alertas via pskit notify, sem nunca ver a credencial do canal.{
"contract_version": 0,
"language": "en",
"scenario": "linux-server",
"machine_name": "myserver",
"brain_home": "/srv/myserver/brain",
"brain_user": "pskit-brain",
"brain_port": 8799,
"session_inbox": "inbox/sessions",
"memory_budget": { "brain_max": 10.0, ... },
"notify_command": "/usr/local/bin/pskit notify",
"heavy_lock": "/run/pskit/heavy.lock"
}
Never below 1 GiB, never above a third of RAM. With no manifest yet, the brain gets 31.9% of RAM, rounded down in 256 MiB steps: 10 GiB on a 32 GiB machine.
Nunca abaixo de 1 GiB, nunca acima de um terço da RAM. Sem manifesto, o brain recebe 31,9% da RAM, arredondado para baixo em passos de 256 MiB: 10 GiB numa máquina de 32 GiB.
services[]resident (always on, restarted) or scheduled; absolute command; optional heavy lock and timeoutresidente (sempre ligado, reiniciado) ou agendado; comando absoluto; trava pesada e timeout opcionaisscheduleevery N minutes, daily at HH:MM, or weeklya cada N minutos, diário às HH:MM ou semanalhealtha loopback URL whose JSON says status okuma URL de loopback cujo JSON diz status okbackupwhat to include and exclude inside its homeo que incluir e excluir dentro da sua casapeak_memorymeasured resident and batch peakspicos medidos, residente e de lotee2e_testa command that proves the brain works; run during the final proofum comando que prova que o brain funciona; roda na prova finalenvironmentplain settings, never secretsconfigurações simples, nunca segredos{
"manifest_version": 0,
"name": "example-brain",
"services": [
{ "name": "query", "kind": "resident" },
{ "name": "capture", "kind": "scheduled",
"schedule": { "daily_at": ["05:00", "12:00"] },
"heavy_lock": true }
],
"health": { "url": "http://127.0.0.1:8799/health" },
"backup": { "include": ["vault", "state"],
"exclude": ["index", "models"] },
"peak_memory": { "resident_mib": 2048,
"batch_mib": 3072 },
"e2e_test": { "command": [...] }
}
pskit notify, never silentlyavisar falhas por pskit notify, nunca em silênciosudo pskit brain validate FILEsudo pskit brain apply FILE
Python standard library only, 3.9 or newer, so nothing has to be installed before the installer. About 8,100 lines of code, 36 installed templates and 385 messages in each language.
Só a biblioteca padrão do Python, 3.9 ou mais novo, para nada precisar ser instalado antes do instalador. Cerca de 8.100 linhas de código, 36 templates instalados e 385 mensagens em cada idioma.
INSTALLERThe flow, every step, unattended installs.
O fluxo, cada passo, instalação sem interação.
OPERATIONSDaily life, updates, devices, restoring from backup.
O dia a dia, atualizações, dispositivos, restaurar do backup.
TROUBLESHOOTINGWhat to do when something fails.
O que fazer quando algo falha.
SECURITYThreat model and every protection.
Modelo de ameaças e cada proteção.
HOST-BRAIN-CONTRACTThe interface for the brain layer.
A interface para a camada do brain.
STRUCTUREThe host layout, component by component, and why each piece exists.
O layout do host, componente por componente, e por que cada peça existe.
DECISIONSWhat was decided and why; what is still open.
O que foi decidido e por quê; o que segue aberto.
TESTINGWhat is proven, where, and what is not yet.
O que está provado, onde, e o que ainda não está.
| D1 | Machines without LVM get directories on the existing disk, with disk alerts. A running machine's root disk cannot be repartitioned by an installer. | Máquinas sem LVM recebem pastas no disco existente, com alertas de disco. Um instalador não reparticiona o disco raiz de uma máquina em uso. | decideddecidido |
| D2 | One SSH channel, filtered by the firewall. Binding sshd to the tailnet address is a known cause of SSH not coming back after a reboot. | Um canal SSH, filtrado pelo firewall. Prender o sshd ao endereço da tailnet é uma causa conhecida de o SSH não voltar depois de um reboot. | decideddecidido |
| D3 | Backup to S3-compatible storage first, another owned machine second, a local disk with a warning third. Never a laptop by default. | Backup em armazenamento compatível com S3 primeiro, outra máquina própria em segundo, disco local com aviso em terceiro. Nunca um laptop por padrão. | decideddecidido |
| D4 | Default alert channel. Implemented with Telegram as the default and ntfy as the alternative; the final default is the author's call. | Canal padrão de alertas. Implementado com Telegram como padrão e ntfy como alternativa; o padrão final é decisão do autor. | author's calldecisão do autor |
| D5 | Minimum hardware: refuse below about 4 GiB of RAM or 10 GiB of free disk, warn below 8 and 30. To revisit with the brain's measured peaks. | Hardware mínimo: recusa abaixo de cerca de 4 GiB de RAM ou 10 GiB de disco livre, avisa abaixo de 8 e 30. A revisar com os picos medidos do brain. | provisionalprovisório |
| D6 | Agent histories that fill the disk are reported in the daily summary, never moved or deleted. | Históricos de agentes que enchem o disco aparecem no resumo diário, nunca são movidos nem apagados. | decideddecidido |
| D7 | Name, license, public or private. Name personal-server-kit, command pskit, public repository under the PolyForm Noncommercial 1.0.0 license. | Nome, licença, público ou privado. Nome personal-server-kit, comando pskit, repositório público sob a licença PolyForm Noncommercial 1.0.0. | decideddecidido |
| D8 | Which systems can be the server. Linux only (Ubuntu 24.04): macOS cannot enforce memory limits and FileVault blocks an unattended boot. A Mac stays supported as the owner's laptop. | Quais sistemas podem ser o servidor. Só Linux (Ubuntu 24.04): o macOS não garante limite de memória e o FileVault impede o boot sem ninguém. O Mac continua suportado como laptop do dono. | decideddecidido |