Building a Terminal Portfolio You Can SSH Into

TL;DR

You can now browse this site in your terminal:

ssh agnelnieves.sh

The setup

Why I built it

I do side projects like this when I need to step away from whatever I'm shipping day-to-day. They're not pitches. They don't need a thesis. They're more like the way some people fix a bike on a Saturday: sit down, follow whatever's pulling on your curiosity, and at the end you have a thing that didn't exist before. That's the whole reason.

The architecture

One binary. Two modes. One render path.

            ┌─────────────────────────────┐
            │     agnel  (single .exe)    │
            └──────────────┬──────────────┘
                           │
            ┌──────────────┴──────────────┐
            │                             │
       agnel (no flag)             agnel --serve
       Local TUI                   SSH server (Fly.io)
       crossterm stdin             russh + custom backend
            │                             │
            └──────────┬──────────────────┘
                       │
                src/render.rs   ← shared
                       │
                Per-session App state
                       │
                Live fetches from agnelnieves.com APIs

The pieces:

• TUI: ratatui draws everything: header, ticker, ASCII banner, projects list, blog reader. The render function lives in src/render.rs and is identical whether the binary is running on your laptop or whether you're seeing it over SSH.
• State machine: App in src/app.rs owns screen, scroll position, list selection, ticker animation, and async-fetch results funneled through an mpsc::Receiver.
• Data: zero content is bundled. The CLI fetches live from /feed.json, /api/blog/[slug]/raw, /api/projects, and /api/site.json on this site, cached for an hour at ~/.agnel/cache/. So a new blog post here shows up in your terminal immediately without redeploying anything.
• SSH server: russh 0.60 in src/serve.rs. One tokio task per session.

The decision that made it easy: don't fork a PTY

• Adds a libc dependency (forkpty)
• Forks a process per connection (more memory, slower spawn)
• Hard to share state between the SSH layer and the app

struct TerminalSink {
    sender: UnboundedSender<Vec<u8>>,
    sink: Vec<u8>,
}
 
impl std::io::Write for TerminalSink {
    fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
        self.sink.extend_from_slice(buf);
        Ok(buf.len())
    }
    fn flush(&mut self) -> std::io::Result<()> {
        if !self.sink.is_empty() {
            let _ = self.sender.send(std::mem::take(&mut self.sink));
        }
        Ok(())
    }
}

fn parse_keys(buf: &[u8]) -> Vec<KeyEvent> {
    // 0x03 → Ctrl+C, 0x1b[A → Up, 0x1b alone → Esc,
    // printable ASCII → Char(b), etc.
}

The result: a single binary you can drop on a VPS, in a container, or even into a Lambda-style worker, and it just serves the TUI.

What I learned about hosting

A few things I didn't expect.

1. Fly trial orgs block dedicated IPv4, and SSH needs IPv4. For HTTP, Fly's edge gives you a shared anycast IPv4 for free. For raw TCP on port 22, you need a dedicated v4 (~$2/mo), and trial orgs can't allocate one. Pure-IPv6 isn't a real option, either: most US residential ISPs still don't have native IPv6 SSH paths. Adding a card was the unlock.

ANSI Shadow beats slant

Visitor #N

There's no leaderboard. No real meaning to the number. But watching it tick up after shipping is the moment the whole side project starts feeling worth it.

The stack

What's next

• Pretty errors and loading states. Today they say Loading… which is functional but boring.
• Project deep-links. I render project metadata but not the original write-ups. Pulling MDX through the API would let me ship long-form case studies in-terminal.
• Cross-platform release binaries. The current install path is cargo install --path cli/. Homebrew tap + release artifacts for macOS and Linux is a Saturday morning.

Try it

ssh agnelnieves.sh