DEV Community: Luis Gustavo S. Barreto

Remote AI Coding with Claude Code and ShellHub

Luis Gustavo S. Barreto — Fri, 10 Oct 2025 15:37:07 +0000

In the rapidly evolving world of AI-assisted development, having access to powerful AI coding assistants from anywhere has become essential.

I've been a big fan of Claude Code since it launched. Having an AI assistant that can understand large codebases, make thoughtful edits, and actually reason about architecture has been game-changing for my workflow.

But what if you want to access Claude Code remotely, from any device?

When I started a conversation on my laptop, that context stayed there. If I wanted to continue from my desktop, I'd have to re-explain everything. And if I was on my tablet or phone? Forget about it. I needed a way to have my Claude Code environment accessible from anywhere, without losing context or messing with complex networking.

That's when I realized: what if I just containerized Claude Code and made it accessible via SSH through ShellHub?

The Problem

Here's the thing—Claude Code runs locally on your machine. That's great for privacy and speed, but terrible for mobility.

I could have set up a VM in the cloud, but then I'm paying for compute even when I'm not using it. Plus, I wanted to keep my development close to home—sometimes I need access to local hardware, Docker on my machine, or files that shouldn't leave my network.

The Solution: ShellHub + Docker

ShellHub is this cool open-source project that makes SSH access dead simple. No port forwarding, no VPN setup, no dynamic DNS headaches. Devices register with a ShellHub server and become instantly accessible via SSH from anywhere. It's like Tailscale, but specifically designed for SSH access, and you can self-host the server.

The idea is simple:

Run Claude Code in a Docker container
Install ShellHub agent in the container
SSH in from any device and land directly in Claude Code

And since everything runs in Docker, the workspace and Claude's context persist. Start a session on your laptop, continue from your phone using Termius—it all just works.

Setup

The setup is surprisingly straightforward. Here's what we're building:

Base: Alpine Linux (small, fast)
Claude Code: Installed via npm
ShellHub Agent: Downloaded from GitHub releases
User shell: Bash configured to auto-launch Claude Code
Workspace: Persistent directory for your code

The clever bit is in how we handle the shell. When you SSH in, ShellHub runs bash --login. We configure the ~/.profile to automatically exec into Claude Code for interactive SSH sessions.

This means:

SSH in → bash loads → .profile runs → Claude Code launches
You land directly in Claude Code without typing any commands
Non-interactive commands (like scp) work normally

Let's build it.

The Dockerfile

I wanted to keep this lean. Alpine Linux as the base gives us a tiny image (~200MB total), and we only install what we need:

FROM alpine:3.19

# Install dependencies
RUN apk add --no-cache \
    nodejs \
    npm \
    bash \
    curl \
    ca-certificates \
    git \
    openssh-client \
    sudo

# Install Claude Code CLI
RUN npm install -g @anthropic-ai/claude-code

# Download and install ShellHub agent binary
RUN curl -L https://github.com/shellhub-io/shellhub/releases/download/v0.21.0-rc.2/shellhub-agent-linux-amd64.gz -o /tmp/shellhub-agent.gz && \
    gunzip /tmp/shellhub-agent.gz && \
    mv /tmp/shellhub-agent /usr/local/bin/shellhub-agent && \
    chmod +x /usr/local/bin/shellhub-agent

# Create claudeuser with bash as shell and home directory
RUN adduser -D -s /bin/bash -h /home/claudeuser claudeuser && \
    echo "claudeuser ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers

# Create workspace directory inside user home
RUN mkdir -p /home/claudeuser/workspace && \
    chown -R claudeuser:claudeuser /home/claudeuser

# Copy profile configuration
COPY profile /home/claudeuser/.profile
RUN chown claudeuser:claudeuser /home/claudeuser/.profile

# Copy entrypoint script
COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh

ENTRYPOINT ["/entrypoint.sh"]

A few notes on design choices:

I download the ShellHub agent binary directly from GitHub releases
The user gets /bin/bash as their shell in /etc/passwd. I initially tried setting the shell to /usr/local/bin/claude directly, but ShellHub's --login flag doesn't play nice with non-standard shells
Workspace lives in the user's home directory (/home/claudeuser/workspace), which makes permissions straightforward

The Profile Magic

Here's where it gets interesting. The .profile file is what actually launches Claude:

#!/bin/bash

# Set working directory to workspace
cd ~/workspace 2>/dev/null || cd ~

# Check if this is an interactive shell
if [[ $- == *i* ]]; then
    # Launch Claude Code for interactive sessions
    exec /usr/local/bin/claude
fi

The $- variable contains shell flags. When i is present, you've got an interactive shell. The exec is key—it replaces the bash process with Claude Code, so when you exit Claude, the SSH session terminates cleanly.

Why check for interactive? Because scp, automated scripts, and other non-interactive SSH commands need to work. Without this check, trying to scp a file would launch Claude Code instead. Not ideal.

The Entrypoint

The entrypoint starts the ShellHub agent:

#!/bin/bash

# Configure ShellHub agent (agent reads from env vars directly)
if [ -z "$SHELLHUB_TENANT_ID" ]; then
    echo "ERROR: SHELLHUB_TENANT_ID environment variable is required"
    exit 1
fi

if [ -z "$SHELLHUB_SERVER_ADDRESS" ]; then
    echo "ERROR: SHELLHUB_SERVER_ADDRESS environment variable is required"
    exit 1
fi

# Start ShellHub agent in background (configured via env vars)
echo "Starting ShellHub agent..."
/usr/local/bin/shellhub-agent &

AGENT_PID=$!

echo "ShellHub agent started (PID: $AGENT_PID)"
echo "Claude Code shell ready for connections"
echo "Workspace: /home/claudeuser/workspace"

# Keep container running and monitor agent
wait $AGENT_PID

Running It

Build the image:

docker build -t shellhub-claude-code .

Run the container (adjust the values for your setup):

docker run --rm \
  -e SHELLHUB_TENANT_ID=00000000-0000-4000-0000-000000000000 \  # Your tenant ID from ShellHub
  -e SHELLHUB_SERVER_ADDRESS=http://172.17.0.1 \                # Your ShellHub server address
  -e SHELLHUB_PRIVATE_KEY=/etc/shellhub/shellhub.key \          # Path inside container to key
  -e SHELLHUB_PREFERRED_HOSTNAME=claudecode \                   # Device name in ShellHub
  -v ./keys:/etc/shellhub \                                      # Mount local keys directory
  -v ./workspace:/home/claudeuser/workspace \                    # Mount local workspace
  shellhub-claude-code

You'll need to:

Replace SHELLHUB_TENANT_ID with your tenant ID from the ShellHub dashboard
Replace SHELLHUB_SERVER_ADDRESS with your ShellHub server URL
Create a ./keys directory with your shellhub.key file (if using device authentication)
Create a ./workspace directory for your code files

The container starts, the ShellHub agent registers with your server, and the device shows up in your dashboard. Accept it, and you're good to go.

Connecting

Once your device is registered and accepted in ShellHub, you'll see it in the dashboard with connection details:

You can connect in two ways:

Option 1: Through the ShellHub UI
Click the terminal icon in the dashboard (as shown above) to open a web-based SSH session directly in your browser.

Option 2: Using your SSH client

ssh claudeuser@namespace.claudecode@your-shellhub-server

Either way, you land directly in Claude Code. No commands to run, no setup.

First time connecting? Claude Code will automatically prompt you to authenticate. It'll generate a link for you to visit—just open it, get your authentication token, and paste it back into Claude Code. That's it. From now on, you've got Claude available from anywhere.

And just like that, you're in:

I can start a conversation on my laptop, SSH in from my phone on Termius during my commute, and pick up exactly where I left off. The workspace persists, Claude's context persists—it all just works.

Why This Works

It works everywhere. Your container can be behind NAT, on a residential IP, wherever. ShellHub handles the networking. No port forwarding, no dynamic DNS, no VPN.

Any device with SSH. Laptop, desktop, tablet, phone. Even a friend's computer if you trust them with your SSH key. ShellHub only needs a standard SSH client.

Context persists. Unlike starting fresh each time, your Claude conversations and workspace state survive between sessions.

It's yours. Self-hosted, open source, no vendor lock-in. You control where it runs and who has access.

Things to Know

Single user: This setup is for one person at a time. Multiple SSH sessions will fight over the same Claude instance. For teams, spin up separate containers per user.

API keys: Claude stores your API key in /home/claudeuser. If you don't persist that directory with a volume, you'll need to /login again after container restarts.

Why Not Just Use...

Tailscale? Tailscale requires installing software on every device you want to access from. ShellHub just needs SSH—works great on shared computers or locked-down environments.

Direct SSH? Sure, if you want to deal with port forwarding, dynamic DNS, or paying for a static IP. ShellHub makes all that disappear.

Final Thoughts

This setup has become part of my daily workflow. I've got Claude accessible from my home lab, reachable from anywhere. No friction, no complexity, just works.

The whole thing is maybe 100 lines of code across a Dockerfile and shell scripts. But it solves a real problem: making AI-assisted development truly portable.

If you've been wanting remote access to Claude Code without cloud vendor lock-in, give this a try.

Dominando SCM_RIGHTS: Transferência de WebSocket entre processos no Linux

Luis Gustavo S. Barreto — Fri, 08 Aug 2025 19:21:31 +0000

As instâncias do ShellHub Enterprise lidam com dezenas de milhares de conexões WebSocket concorrentes, além de múltiplas requisições por segundo nos endpoints HTTP da nossa API.

Em cada instância nós temos um API proxy baseado em Nginx/Openresty que centraliza todo o tráfego HTTP do servidor, ou seja, todas as rotas públicas passam por ele, como rotas do painel de administração Web, rotas que o agent do ShellHub rodando nos dispositivos acessa, além do próprio túnel WebSocket que é estabelecido entre eles e também APIs de integração dos nossos clientes batendo em alguns endpoints.

Tudo isso gera um grande consumo de recursos do servidor como processamento e memória (geralmente o mais caro). Para nos mantermos competitivos nesse mercado ultra nichado, nossa stack foi projetada meticulosamente para ser a menor possível e entregar o máximo possível sem abrir mão da excelência técnica (foco do open source).

Embora o uso do nginx como proxy central traga essa simplicidade operacional, entregando um controle centralizado, gerenciamento automático de certificados HTTPS, roteamento para cada serviço da nossa stack, ele acaba se tornando um ponto crítico de acúmulo de carga.

E no caso específico do WebSocket (onde nossa tecnologia se baseia), essa arquitetura implica que o nginx mantém duas conexões ativas para cada cliente: uma com o cliente final (downstream) e outra com o backend (upstream). Para cada mensagem WebSocket, há cópias entre o espaço de usuário e o kernel, buffers alocados por conexão e vários context switches. Com dezenas de milhares de conexões WebSocket ativas isso consome muitos recursos.

Diante dessa problemática, gostaria de compartilhar como otimizar esse processo utilizando técnicas avançadas do próprio kernel Linux, como a passagem de file descriptors (sockets) via SCM_RIGHTS, que são um tanto quanto desconhecidas por muitos, mas que podem ser muito úteis em diminuir consumo de recursos de um servidor.

O Problema Fundamental: Proxy como Middleman

A arquitetura tradicional de WebSockets em produção segue um padrão bem estabelecido:

Neste modelo, o Nginx atua como um intermediário constante, mantendo duas conexões para cada cliente: uma upstream e uma downstream. Para cada mensagem trocada, os dados são:

Lidos do kernel para o espaço do usuário (Nginx)
Processados pelo Nginx
Escritos de volta ao kernel
Enviados para o backend ou cliente

Esta arquitetura, embora simples e amplamente adotada, possui limitações inerentes:

Overhead de Memória: O Nginx aloca buffers para cada conexão ativa
Latência Adicional: Cada hop introduz latência de processamento
CPU Overhead: Context switches entre processos e cópias desnecessárias de dados

O Nginx mantém dois file descriptors para cada cliente: um para o cliente final e outro para o backend. Cada mensagem WebSocket precisa:

read(5) - ler do cliente
write(6) - escrever para o backend
read(6) - ler resposta do backend
write(5) - escrever para o cliente

A Solução: `SCM_RIGHTS` e a transferência de file descriptors

O SCM_RIGHTS é um mecanismo do kernel Linux que permite a transferência de file descriptors abertos entre processos através de Unix Domain Sockets. Esta funcionalidade, presente nos sistemas Unix desde os anos 90, oferece uma capacidade única: transferir a propriedade de uma conexão de rede de um processo para outro.

O que é um File Descriptor?

Um file descriptor (FD) é simplesmente um número inteiro que o kernel usa como "índice" para identificar arquivos, sockets de rede, pipes ou qualquer recurso de I/O aberto por um processo. É como um "ID único" que o processo usa para se referir a uma conexão específica.

Por exemplo: quando seu processo abre uma conexão TCP, o kernel retorna o número 5. A partir daí, sempre que você quiser ler/escrever nessa conexão, você usa read(5) ou write(5).

Como Funciona no Kernel

Quando um processo envia um file descriptor via SCM_RIGHTS:

O kernel não transfere apenas o número do descriptor
Ele cria uma nova entrada na tabela de FDs do processo receptor
Ambas as entradas apontam para a mesma estrutura de arquivo interno
O contador de referência é incrementado
O processo receptor pode usar o FD como se tivesse criado a conexão originalmente

Esta operação é atômica e zero-copy no nível do kernel.

A mágica do `SCM_RIGHTS`

O SCM_RIGHTS permite que o processo A diga para o processo B: "Ei, pega essa conexão aqui e assume ela".

No nível do kernel, isso significa:

Processo Nginx tem FD=5 apontando para uma struct de socket
Via SCM_RIGHTS, o kernel duplica essa referência no processo do backend
Agora o processo do backend também tem um FD (digamos FD=3) apontando para a mesma struct de socket
É a mesma conexão TCP, só que agora dois processos podem acessá-la

Após a transferência:

O Nginx "esquece" da conexão (fecha seu FD=5), e o backend assume toda a comunicação diretamente. Zero overhead de proxy, zero cópias extras, zero context switches desnecessários.

A operação é atômica porque o kernel garante que a referência não seja perdida durante a transferência, e é zero-copy porque não há movimento de dados, apenas manipulação de ponteiros internos do kernel.

Implementação: A Stack Nginx + Lua + Go

Nossa implementação utiliza uma combinação de tecnologias especificamente escolhidas para realizar um processo em etapas bem definidas:

Visão geral do que vamos fazer:

Nginx recebe a conexão e realiza o handshake WebSocket completo
Extraímos o file descriptor da estrutura interna do Nginx usando FFI
Transferimos esse FD para o backend Go via Unix Domain Socket usando SCM_RIGHTS
Go recebe o FD e converte em uma conexão TCP nativa
Nginx substitui o FD original por um dummy e sai de cena
Go assume completamente a comunicação direta com o cliente

Agora vamos implementar cada etapa:

Etapa 1: Nginx - Recepção e Handshake WebSocket

O Nginx funciona como o ponto de entrada, realizando apenas o setup inicial:

location /ws/fd_transfer {
    content_by_lua_block {
        local websocket = require "resty.websocket.server"
        local ws, err = websocket:new{
            timeout = 5000,
            max_payload_len = 1024
        }

        if not ws then
            ngx.log(ngx.ERR, "failed to create websocket: ", err)
            return
        end

        local handler = require "ws_handler"
        handler.handle(ws.sock)

        ws:send_close()
    }
}

Quando o cliente conecta em /ws/fd_transfer e solicita upgrade para WebSocket, o Nginx realiza o handshake WebSocket completo, estabelecendo uma conexão ativa com o cliente.

E aqui entra o ponto crítico da solução: em vez de começar a fazer proxy das mensagens entre as duas pontas, o Nginx chama handler.handle(ws.sock) que extrai o FD da conexão TCP subjacente e transfere via SCM_RIGHTS para o backend através de Unix socket. Então substitui o FD original por um dummy e encerra sua participação com ws:send_close().

Etapa 2: Extração do File Descriptor com FFI

Outro ponto importante da implementação é a extração do FD da estrutura interna do Nginx:

local function get_socket_fd(sock)
    if not sock or not sock[1] then
        return nil, "invalid websocket object"
    end

    local u = ffi.cast("ngx_http_lua_socket_tcp_upstream_s*", sock[1])
    if not u or not u.peer or not u.peer.connection then
        return nil, "invalid upstream socket structure"
    end

    return tonumber(u.peer.connection.fd)
end

Esta função utiliza FFI (Foreign Function Interface) para acessar diretamente as estruturas internas do Nginx, extraindo o file descriptor da conexão TCP subjacente. É uma operação de baixo nível que "vasculha" a memória do processo Nginx para encontrar o número do file descriptor.

Etapa 3: Transferência via SCM_RIGHTS

O fd_manager.lua implementa o protocolo de transferência:

function M.send_fd(path, fd)
    local sock = C.socket(C.AF_UNIX, C.SOCK_STREAM, 0)

    -- Preparação da mensagem de controle SCM_RIGHTS
    local control_len = ffi.sizeof("struct cmsghdr") + ffi.sizeof("int")
    local control = ffi.new("char[?]", control_len)
    local cmsg = ffi.cast("struct cmsghdr*", control)

    cmsg.cmsg_len = control_len
    cmsg.cmsg_level = C.SOL_SOCKET
    cmsg.cmsg_type = C.SCM_RIGHTS

    -- Insere o FD na mensagem de controle
    ffi.cast("int*", control + ffi.sizeof("struct cmsghdr"))[0] = fd

    -- Envia via sendmsg
    local msg = ffi.new("struct msghdr")
    msg.msg_control = control
    msg.msg_controllen = control_len

    return C.sendmsg(sock, msg, 0) >= 0
end

Esta função monta uma mensagem especial do tipo SCM_RIGHTS que contém o file descriptor e a envia através de um Unix Domain Socket para o backend Go. É aqui que acontece a "transferência de propriedade" da conexão.

Etapa 4: Backend Go - Recepção e Conversão

O backend Go implementa o receptor dos file descriptors:

func receiveFD(socket *net.UnixConn) (int, error) {
    buf := make([]byte, 1)
    oob := make([]byte, syscall.CmsgSpace(4))

    _, _, _, _, err := socket.ReadMsgUnix(buf, oob)
    if err != nil {
        return -1, err
    }

    // Parse das mensagens de controle
    msgs, err := syscall.ParseSocketControlMessage(oob)
    if err != nil {
        return -1, err
    }

    // Extração do file descriptor
    fds, err := syscall.ParseUnixRights(&msgs[0])
    if err != nil {
        return -1, err
    }

    return fds[0], nil
}

Uma vez recebido o FD, ele é convertido em uma net.Conn nativa:

file := os.NewFile(uintptr(fd), "websocket_fd")
tcpConn, err := net.FileConn(file)
file.Close()

// Agora tcpConn é uma conexão TCP normal
go handleConnection(tcpConn, fd)

...

func handleConnection(conn net.Conn, fd int) {
    defer conn.Close()

    for {
        // Leitura direta de frames WebSocket
        messages, err := wsutil.ReadClientMessage(conn, nil)
        if err != nil {
            return
        }

        // Processamento frame por frame
        for _, frame := range messages {
            switch frame.OpCode {
            case ws.OpText:
                // Acesso direto ao payload sem cópias
                wsutil.WriteServerText(conn, frame.Payload)
            case ws.OpBinary:
                wsutil.WriteServerBinary(conn, frame.Payload)
            }
        }
    }
}

A partir desse momento, o backend Go está falando diretamente com o cliente original, como se tivesse criado a conexão desde o início.

Detalhes Técnicos Críticos

1. Substituição por Socket Dummy

Após transferir o FD, precisamos "enganar" o Nginx substituindo o file descriptor original
por um "dummy" para quando o nginx for liberar recursos não fechar o socket que agora pertence ao processo do backend.

function M.replace_with_dummy(fd)
    local dummy = C.socket(C.AF_INET, C.SOCK_STREAM, 0)
    if dummy == -1 then
        return false, "failed to create dummy socket"
    end

    -- dup2 substitui o FD original pelo dummy
    if C.dup2(dummy, fd) == -1 then
        C.close(dummy)
        return false, "dup2 failed"
    end

    C.close(dummy)
    return true
end

2. Parsing de Frames WebSocket com `gobwas/ws`

Quando o backend Go recebe o file descriptor via SCM_RIGHTS, ele herda uma conexão TCP que já está "promovida" para WebSocket pelo Nginx. Isso significa que:

O handshake HTTP → WebSocket já foi realizado
A conexão está no estado WebSocket
Todos os dados subsequentes são frames WebSocket

Por isso, não podemos usar bibliotecas WebSocket convencionais como gorilla/websocket, que esperam fazer o handshake completo desde o início. Precisamos de uma biblioteca que faça apenas o parsing dos frames WebSocket.

Benchmarking: Dados Concretos de Performance

O benchmark automatizado compara duas arquiteturas:

Proxy Tradicional (/ws/proxy): Nginx faz proxy das mensagens
Com SCM_RIGHTS (/ws/fd_transfer): Nginx transfere a conexão

Metodologia

Ferramenta: k6 para geração de carga
Conexões: 10.000 WebSockets simultâneas
Duração: 60 segundos por teste
Monitoramento: Prometheus com métricas de containers
Espera: 15 segundos para estabilização da carga

Resultados

Endpoint	Backend CPU (cores)	Backend Mem (MB)	Nginx CPU (cores)	Nginx Mem (MB)	Active WS
`/ws/proxy`	0.0170	143.54	0.0074	331.89	10000
`/ws/fd_transfer`	0.0211	116.43	0.0005	55.03	10000

Análise dos Resultados

Memória Nginx: Redução de 331.89 MB → 55.03 MB (83.4% de redução)

O handoff libera o Nginx de manter buffers para 10.000 conexões
Memória residual reflete apenas overhead do processo base

CPU Nginx: Redução de 0.0074 → 0.0005 cores (93.2% de redução)

Nginx não processa mensagens WebSocket após o handoff
CPU residual é apenas para aceitar novas conexões

Backend: Ligeiro aumento de CPU (0.0170 → 0.0211), redução de memória (143.54 → 116.43 MB)

Aumento de CPU esperado: backend assume todo o I/O da rede
Redução de memória: gobwas/ws trabalha apenas com frames WebSocket e consome menos memória

Implicações Arquiteturais

Vantagens

Escalabilidade Horizontal: Nginx pode aceitar muito mais conexões
Latência Reduzida: Eliminação do hop intermediário
Eficiência de Recursos: Melhor utilização de CPU e memória
Separação de Responsabilidades: Nginx foca em roteamento, backend em lógica

Limitações

Complexidade: Implementação significativamente mais complexa
Dependência de Plataforma: Específico para sistemas Unix/Linux
Debugging: Mais difícil rastrear conexões após handoff
Estado Compartilhado: Coordenação entre Nginx e backend é crítica

Casos de Uso Ideais

Aplicações de High-Frequency Trading: Onde cada microssegundo importa
Jogos Multiplayer: Latência crítica para experiência do usuário
Sistemas IoT: Grande volume de conexões com mensagens pequenas
Streaming de Dados: Onde throughput máximo é essencial

Conclusão

A passagem de FD via SCM_RIGHTS entre processos pode ajudar aplicações que exigem performance extrema. Embora adicione complexidade, os ganhos em eficiência e escalabilidade são substanciais.

Esta técnica não é adequada para todas as aplicações, mas para cenários onde performance é crítica, ela oferece uma vantagem competitiva significativa. À medida que as aplicações em tempo real se tornam mais críticas, dominar técnicas de baixo nível como SCM_RIGHTS do kernel Linux se torna essencial para arquitetos de sistemas que buscam extrair o máximo desempenho da infraestrutura disponível.

How to Escape from a Container

Luis Gustavo S. Barreto — Wed, 06 Aug 2025 19:01:56 +0000

When I started designing ShellHub, one of the main goals was to make installation easy. I wanted users to be able to test and use the product with minimal barriers and friction. Even though the "users" were developers, I believed that the simpler the beginning, the greater the chance someone would give the project a try. And looking back, I think this was indeed one of the reasons for ShellHub's success.

Right from the start, it became very clear that distributing ShellHub in containers would make things much easier. Because, let's face it, what developer today doesn't have Docker installed either on their local machine or on servers? This choice made everything simpler, from deployment to initial testing. And so it was.

But this decision led me to face a major Linux engineering challenge. How could ShellHub, running inside a container, offer a shell that operated directly on the host operating system and not in the container's isolated environment?

The solution I developed was a way to make a process escape from the container and be, in a way, "teleported" to the host. And when I say "escape," I'm not talking about exploiting security flaws or anything like that. What I built was a secure bridge, using Docker's own resources and Linux kernel tools. Everything within the rules.

In this post, I want to tell you how I built this bridge. I divide it into two parts: the foundation (container configuration with Docker) and the crossing (what makes the magic happen in Linux).

The Complete Flow

Before diving into the details, I'll show you how the general flow works:

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│     User        │───▶│   Container     │───▶│     Host        │
│   connects      │    │  (ShellHub      │    │  (real shell)   │
│                 │    │    Agent)       │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              │                         ▲
                              │                         │
                              └──── nsenter + setpriv ──┘

Part 1: The Foundation – Preparing the Container with Docker

The foundation of the solution lies in how the agent container is started. Everything begins with docker run and some flags that give the container sufficient permissions and visibility to see and interact with the real host.

The Essential Flags

--privileged: This flag gives the container elevated permissions within the kernel, allowing it to access devices, mount namespaces, use setuid, among other things that normal containers can't do. It's the key that opens the doors for the operations we'll do later.

--pid=host: This makes the container share the process namespace with the host. With this flag, the agent can see all processes running on the real system, including the init process (PID 1), which will be fundamental in the next step.

--network=host: This puts the container on the same network stack as the host, which eliminates the need to map ports and facilitates any communication the agent needs to make. It also ensures the shell has access to the same network the user would expect on the host.

The Critical Volumes

-v /:/host: This volume mounts the host's filesystem inside the container, at the /host path. This is how the agent gets access to the entire real filesystem, from /etc to /home, /var, and everything else.

-v /etc/passwd:/etc/passwd:ro, -v /etc/group:/etc/group:ro, -v /etc/shadow:/etc/shadow:ro: These files are mounted so the agent can read the host's user data and know exactly who it's dealing with. Without this, it would be impossible to switch users correctly.

The Complete Command

The agent container is started with something like this:

docker run -d \
  --name shellhub-agent \
  --privileged \
  --pid=host \
  --network=host \
  -v /:/host \
  -v /etc/passwd:/etc/passwd:ro \
  -v /etc/group:/etc/group:ro \
  -v /etc/shadow:/etc/shadow:ro \
  shellhub/agent

With this, the container has everything: access to the host's filesystem, visibility of real processes, shared network, and sufficient permissions to start commands in the host context. The bridge is built. Now it's time to cross.

Part 2: The Crossing – How to Exit the Container Safely

With host access guaranteed, the next step is to start a process that actually runs on the real system, even though it's initiated from within the container.

The Main Tool: `nsenter`

The first tool that comes into play is nsenter (namespace enter). With it, you can enter another process's namespaces. And since the container is using --pid=host, it can see process PID 1 on the host (usually systemd or init).

From there, the agent uses nsenter to launch a new process already within the correct namespaces:

mount: Host filesystem
uts: Host hostname and domainname
ipc: Host inter-process communication
net: Host network stack
pid: Host process tree

nsenter --target 1 --mount --uts --ipc --net --pid

Security Control: `setpriv`

The process born from nsenter is already outside the container, running in the host context. But there's still a problem: this process would be executed as root, since it's started by the privileged container. That would give users way more privileges than they should have.

That's where setpriv comes in. With it, you can drop privileges and switch UID and GID before executing the shell. This way, the process assumes the real user identity on the system and doesn't carry any permissions it shouldn't have.

Important setpriv flags:

--reuid: Sets the real and effective UID
--regid: Sets the real and effective GID
--clear-groups: Removes all supplementary groups

The Final Command

The final command that the agent dynamically builds looks like this:

nsenter --target 1 --mount --uts --ipc --net --pid -- \
  setpriv --reuid 1001 --regid 1001 --clear-groups -- \
    /bin/bash --login

This command:

Enters the host via nsenter
Switches to the correct user via setpriv
Starts a clean shell with --login

Security Aspects

What This Approach Mitigates

Unnecessary isolation: Instead of creating abstraction layers that would make usage difficult, we provide direct access to what the user needs, but in a controlled way.

Privilege escalation: Using setpriv ensures that even though the agent runs as root in the container, the end user's shell has only the permissions it should have on the host.

Context leakage: Since we use all host namespaces, there's no confusion between the container environment and the real host environment.

Why `setpriv` is Crucial

Without setpriv, any process started by the agent inherits root permissions. This is a serious security problem, as it would give the end user more privileges than they should have.

setpriv works as a "safety valve" that:

Removes unnecessary capabilities
Sets correct UID/GID
Clears supplementary groups
Ensures the child process cannot recover privileges

Limitations and Precautions

Privileged container: Using --privileged is necessary but brings responsibilities. The agent needs to be trustworthy, since it has full access to the host.

Attack surface: Although the final shell is secure, the agent itself has elevated privileges. It's crucial to keep the agent code simple and auditable.

Kernel dependencies: The solution depends on specific Linux kernel features (nsenter, namespaces, etc). It doesn't work on FreeBSD which has a different installation method.

The Complete Flow in Practice

In practice, when a user connects to ShellHub, what happens is:

Connection reception: The agent, running inside the container, receives the SSH connection request.
User identification: The agent queries the /etc/passwd and /etc/group files (which are mounted from the host) to identify the correct UID/GID for the user.
Command assembly: It dynamically builds an nsenter + setpriv command specific to that user:

   nsenter --target 1 --mount --uts --ipc --net --pid -- \
     setpriv --reuid {user_uid} --regid {user_gid} --clear-groups -- \
       {user_shell} --login

Execution and bridging: The command is executed, creating a process that:
- Runs in the host context (thanks to nsenter)
- Has the correct user permissions (thanks to setpriv)
- Offers a fully functional shell on the real system
Communication: The stdin/stdout/stderr of this process are connected to the SSH session, creating a transparent experience for the user.

This entire process happens securely, without exploits and without tricks.

Engineering Lessons

Simplicity as a non-functional requirement: Treating ease of use as a real technical requirement, not as "nice to have," forced more creative solutions.

Limitations generate innovation: The decision to use Docker created a technical limitation that resulted in a more elegant solution than traditional alternatives.

Tools exist for a reason: Instead of reinventing the wheel, creatively combining nsenter and setpriv solved a complex problem with minimal code.

Security from the start: Thinking about security from conception (with setpriv) avoided rework and future problems.

Conclusion

The decision to use Docker, which initially was just to make installation easier, ended up forcing me to solve a deep technical problem. And the solution I found is one of the parts of ShellHub I'm most proud of. No tricks. Just engineering, reasoning, and creative use of tools that already existed.

If you're facing a similar problem, remember: sometimes the best solution is combining existing tools in new ways, instead of building something from scratch. Linux already gives you the pieces, you just need to know them well enough to put them together creatively.

drera-labs: Terminal website

Luis Gustavo S. Barreto — Tue, 29 Jul 2025 19:16:55 +0000

I built a personal website that isn't a typical website. Instead of using HTML and CSS, it runs entirely inside a terminal user interface (TUI). You can access it in two ways:

From your browser: www.dreralabs.xyz (which runs in a terminal emulator over WebSocket)
Directly from your terminal: ssh www.dreralabs.xyz

In this post, I'll show you how this crazy idea works, the architecture behind it, and the tools that made it possible.

The Idea: Why a Website in the Terminal?

As a Linux and command-line enthusiast, I spend most of my day in a terminal. The idea for Drera Labs came from a question: "What if my personal website was an extension of my favorite work environment?".

I wanted to create something that was:

Fast and lightweight: Without the overhead of heavy JavaScript frameworks.
Interactive: Using TUI tools to create a "glamorous" terminal experience.
Accessible: Available to those who prefer the convenience of the web and those who live in the terminal.

The result is a site where navigation, reading posts, and even submitting forms happen in a shell environment.

How It Works: The Architecture

The project's magic lies in unifying web and SSH access into a single terminal experience. The backend is written in Go and orchestrates everything.

Here's a summary of the architecture:

Dual Entry Point:
- An HTTP/WebSocket server (port 8080) serves a minimal HTML page that opens a WebSocket connection.
- An SSH server (port 2221) accepts direct connections from SSH clients.
WebSocket to SSH Proxy:
On the frontend, the browser runs a terminal emulator built with xterm.js. When a client connects via the browser, the Go server doesn't interpret the commands. Instead, it acts as a proxy, opening a connection to its own local SSH server. This is the key trick: every interaction, whether from the web or SSH, is treated as a standard SSH session. This vastly simplifies the logic, as we only need to worry about managing SSH sessions.
Session Management with Zellij:
For each new connection, the server starts a Zellij session, a modern terminal multiplexer. Zellij is configured with two main files:
- layout.kdl: Defines the interface structure, splitting the screen into panes for the navigation bar, content area, and status bars.
- config.kdl: Customizes the theme, shortcuts, and overall behavior of Zellij.
Navigation with Shell Scripts and gum:
Navigation is controlled by a series of shell scripts that communicate through a named pipe (FIFO).
- The navigation pane runs a script that uses gum, a tool for creating "glamorous" TUIs, to display a menu of options.
- When an option is selected, the name of the corresponding script (e.g., blog.sh) is written to the pipe.
- The main content pane has a "router" script that continuously reads from the pipe. When it receives a new command, it executes the appropriate script to display the content for that section.
Content Rendering with glow:
The pages and blog posts are written in Markdown. To display them beautifully in the terminal, the scripts use glow, which renders Markdown on the command line with style.

The Tech Stack

Backend: Go
- Web/WebSocket Server: gorilla/websocket
- SSH Server: gliderlabs/ssh
Frontend:
- Terminal Emulator: xterm.js
Terminal UI:
- Multiplexer: Zellij
- TUI Tools: gum (for menus, forms, etc.)
- Markdown Renderer: glow
Scripting Language: Shell (Bash)
Containerization: Docker and HAProxy

Conclusion

Drera Labs is a fun experiment that explores the boundaries between the web and the terminal. It shows that it's possible to create rich, interactive experiences using only the tools that many of us already love and use every day.

The project is open source, and you can check out the full repository on GitHub: github.com/gustavosbarreto/drera-labs

Feel free to explore, give feedback, or even fork it to create your own version. And the next time you think about building a website, maybe consider building it for the terminal!

Why Use ShellHub Instead of a Traditional SSH Server?

Luis Gustavo S. Barreto — Mon, 26 Dec 2022 17:45:37 +0000

ShellHub is a centralized SSH gateway that allows users to remotely access and manage their servers and devices from anywhere, using a web browser or a mobile app. It provides a secure and convenient way to connect to and control your servers and devices, and can help to improve the security of your servers by preventing unauthorized access.

So why use ShellHub instead of a traditional SSH server? Here are some reasons:

Easy access: With ShellHub, you can access your devices and servers from anywhere, using a web browser or a mobile app. This is more convenient than connecting to a traditional SSH server, which requires you to know the server's public IP address and possibly configure the router to allow SSH connections.
Enhanced security: ShellHub offers various security measures to protect your devices and servers. For example, it allows you to create firewall rules to filter SSH connections, only allowing the connections you authorize. It also supports public-key authentication, which can help prevent unauthorized access. In comparison, a traditional SSH server may be more susceptible to hacker attacks.
Simplified access management: ShellHub allows you to create user accounts for each person who needs to access your devices and servers. This can make it easier to manage access, as you can grant or revoke access for individual users without affecting the access of other users. In comparison, a traditional SSH server may be more difficult to manage, as all people who need to access the server need to share the same password or use a private key.
Monitoring and tracking: ShellHub offers audit logging and session recording features, which allow you to monitor and track access to your devices and servers. This can be useful for identifying unauthorized access attempts or for monitoring user activity on your devices. In comparison, a traditional SSH server may be more difficult to monitor and track.

In summary, ShellHub is a valuable tool that offers many advantages over a traditional SSH server for remotely accessing and managing your servers and devices. It allows you to easily access Linux devices behind a firewall and NAT, use standard tools to connect to devices and transfer files securely, manage access to devices using public-key authentication, protect your devices with flexible firewall rules, and monitor access and user activity with audit logging and session recording features.

If you're interested in trying out ShellHub, you have two options: you can either test out the ShellHub Cloud for free, or follow the documentation to set up the Community Edition on your own server.

The ShellHub Cloud is a SaaS (Software as a Service) offering that provides a convenient way to manage your servers and devices from anywhere. It's easy to get started: simply sign up for a free account and you can start using ShellHub right away.

If you prefer to self-host ShellHub, you can follow the documentation to set up the Community Edition on your own server. The Community Edition is open-source and includes the core features of ShellHub.

In addition to the Community and Cloud, ShellHub also offers an Enterprise Edition that is designed for use in a business environment. The Enterprise edition includes all of the features of the Community edition, as well as additional features that are specifically geared towards business use. These features may include things like firewall rules and session recording.

One of the main benefits of the Enterprise Edition is that it can be installed on a dedicated infrastructure, which can provide greater reliability and performance. By running ShellHub on its own dedicated servers or virtual machines, you can ensure that it has the resources it needs to operate smoothly and effectively. This can be especially useful if you have a large number of devices and users that need to access your servers and devices through ShellHub.

Overall, the Enterprise Edition of ShellHub is a powerful and flexible solution that offers a range of features and benefits for businesses. If you need a robust and reliable SSH gateway that can support your business needs, the Enterprise Edition may be the right choice for you.

No matter which option you choose, ShellHub can help you easily and securely access and manage your servers and devices from anywhere. So why wait? Try ShellHub today and see for yourself how it can make your remote access experience better!

If you're interested in contributing to the development of ShellHub, or just want to stay up to date with the latest news and updates, we invite you to join us on GitHub.

Tutorial: How to access Raspberry Pi remotely from anywhere

Luis Gustavo S. Barreto — Wed, 17 Aug 2022 22:53:00 +0000

In this article, we’ll share a brief tutorial to help you access your Raspberry Pi remotely, easily, and fast using a centralized SSH server. We can assure you that our step-by-step guide will make the process much easier.

Once ShellHub can improve your development process, Raspberry Pi boards are a great option to help you achieve success in your projects.

Requirements

On the Raspberry terminal type the following command to install Docker:

sudo apt install docker.io

To launch the Docker, run the command below:

sudo systemctl enable --now docker

Finally, set up the privileges for the current user:

sudo usermod -aG docker $USER

Now reboot the Raspberry Pi to apply the changes:

sudo reboot

Now we’re ready to install ShellHub!

Creating an account on ShellHub

Installing ShellHub on your device is very easy. But before starting to add your devices and enjoy all features available, it’s necessary to create an account on the platform. It’s for free, no credit card is required.

To do that, you only need to access ShellHub Cloud and register yourself.

After registering, you’re able to add up to 3 devices to your account and access them whenever you need them.

Installing ShellHub Agent

Now, it’s time to add the ShellHub agent to the RPI. When you access your account, a wizard will appear, showing the following steps to add devices to your account. Just copy the command, paste into Raspberry PI terminal and run it.

Your device will appear on the screen and you will have to confirm identity by clicking on accept button.

And we finished. Now You can access your RPI in an easy, fast, and safe way. If you have any doubts, feel free to check our documentation or contact us at contact@shellhub.io.

If you’re curious to know more about Shellhub, follow us on Twitter and LinkedIn.

DEV Community: Luis Gustavo S. Barreto

Remote AI Coding with Claude Code and ShellHub

The Problem

The Solution: ShellHub + Docker

Setup

The Dockerfile

The Profile Magic

The Entrypoint

Running It

Connecting

Why This Works

Things to Know

Why Not Just Use...

Final Thoughts

Dominando SCM_RIGHTS: Transferência de WebSocket entre processos no Linux

O Problema Fundamental: Proxy como Middleman

A Solução: SCM_RIGHTS e a transferência de file descriptors

O que é um File Descriptor?

Como Funciona no Kernel

A mágica do SCM_RIGHTS

Após a transferência:

Implementação: A Stack Nginx + Lua + Go

Etapa 1: Nginx - Recepção e Handshake WebSocket

Etapa 2: Extração do File Descriptor com FFI

Etapa 3: Transferência via SCM_RIGHTS

Etapa 4: Backend Go - Recepção e Conversão

Detalhes Técnicos Críticos

1. Substituição por Socket Dummy

2. Parsing de Frames WebSocket com gobwas/ws

Benchmarking: Dados Concretos de Performance

Metodologia

Resultados

Análise dos Resultados

Implicações Arquiteturais

Vantagens

Limitações

Casos de Uso Ideais

Conclusão

How to Escape from a Container

The Complete Flow

Part 1: The Foundation – Preparing the Container with Docker

The Essential Flags

The Critical Volumes

The Complete Command

Part 2: The Crossing – How to Exit the Container Safely

The Main Tool: nsenter

Security Control: setpriv

The Final Command

Security Aspects

What This Approach Mitigates

Why setpriv is Crucial

Limitations and Precautions

The Complete Flow in Practice

Engineering Lessons

Conclusion

drera-labs: Terminal website

The Idea: Why a Website in the Terminal?

How It Works: The Architecture

The Tech Stack

Conclusion

Why Use ShellHub Instead of a Traditional SSH Server?

So why use ShellHub instead of a traditional SSH server? Here are some reasons:

Tutorial: How to access Raspberry Pi remotely from anywhere

Requirements

Creating an account on ShellHub

Installing ShellHub Agent

A Solução: `SCM_RIGHTS` e a transferência de file descriptors

A mágica do `SCM_RIGHTS`

2. Parsing de Frames WebSocket com `gobwas/ws`

The Main Tool: `nsenter`

Security Control: `setpriv`

Why `setpriv` is Crucial