DEV Community: AlpacaX

Work sessions reach the CLI: making bash scripts session-aware

AlpacaX — Mon, 01 Jun 2026 16:30:00 +0000

Your bash script doesn't know it's a privileged session. Your runbook doesn't either. Here's what changes when the CLI itself becomes session-aware.

If you've ever run a production change from a terminal, you've probably written something like this at the top of a remediation script:

#!/usr/bin/env bash
# Production change: ticket INC-2384
# Approved verbally in #incidents by @oncall-lead
# Scope: restart auth-svc on prod-api-{01..04}

That comment is the closest thing to "declared intent" that most shops have. The audit log captures every command the script runs, but it doesn't know why you ran them, who approved them, or where the change starts and stops. When the auditor asks "show me what changed in production last Thursday," you stitch four log sources together the night before the review.

Alpacon's W19 release made the work session a first-class object across the server, web console, and agent—a single named container with declared purpose, an approval gate, a unified timeline, and a post-session summary. The remaining gap was the CLI: the surface where SREs, runbooks, and automation actually live.

With alpacon-cli v1.4.6, that gap closed.

What shipped

alpacon-cli v1.4.6 adds:

A top-level work-session command tree (PR 165)
A --work-session flag on exec, websh, cp, and tunnel, plus work-session use to set the active session for the current workspace (PR 167)
work-session approve, reject, and revoke subcommands (PR 171)

alpacon-web 1.3.15 adds the matching server-side knob: a sudo policy setting that lets operators say "inside an approved work session, skip MFA on sudo" (PR 1150).

If you've read the W19 work-session blog post, the model is the same—declared intent, approval gate, session-scoped sudo, unified timeline, AI summary. This piece is about reaching that model from the terminal.

The CLI flow

Here's an SRE responding to a paging alert on a 200-server fleet. The runbook needs to restart auth-svc on four hosts. Before today, this was a bash one-liner with a comment block. Now it's a session.

1. Open the session with declared purpose.

alpacon work-session create \
  --purpose "INC-2384: restart auth-svc on prod-api-01..04" \
  --scope command \
  --server prod-api-01,prod-api-02,prod-api-03,prod-api-04 \
  --expires-in 2h \
  --wait

The session is created in a pending state with the purpose recorded as a first-class field. --scope declares the access types you need (command, websh, cp, tunnel); --server names the targets; --expires-in (or --expires-at for an absolute RFC3339 timestamp) bounds the window. --wait polls every 10 seconds for up to 30 attempts and returns when the session is approved or rejected, so the requester's terminal blocks here instead of context-switching.

No "approved verbally in #incidents"—the declared intent is the artifact.

2. The approver reviews and approves.

In the realistic on-call flow, the approver is a second engineer on the bridge. They can approve from the web console (where the work-sessions list page now has a filter bar—PR 1150) or from their own CLI:

alpacon work-session approve <session-id>

# Optionally narrow scope or targets at approval time:
alpacon work-session approve <session-id> \
  --scope command \
  --server prod-api-01,prod-api-02

reject <session-id> and revoke <session-id> are the parallel verbs—reject before activation, revoke to force-terminate an approved or active session. All three are superuser-only and the permission check is enforced server-side.

3. Activate the session, pin it for this workspace, then run the change.

alpacon work-session activate <session-id>
alpacon work-session use <session-id>

alpacon exec prod-api-01 -- systemctl restart auth-svc
alpacon exec prod-api-02 -- systemctl restart auth-svc
alpacon exec prod-api-03 -- systemctl restart auth-svc
alpacon exec prod-api-04 -- systemctl restart auth-svc

activate flips the session from approved to active. use writes the active session ID into ~/.alpacon/config.json for the current workspace, so every subsequent exec, websh, cp, and tunnel call attaches the session automatically. Each tagged call prints Using work-session <uuid> to stderr so --output json pipelines stay clean.

Three ways to attach a session, in resolution order:

# 1. Inline flag — overrides everything else, single invocation
alpacon cp ./hotfix.tar.gz prod-api-01:/tmp/ --work-session <session-id>

# 2. Env var — shell-scoped, overrides workspace config, ideal for CI runners
export ALPACON_WORK_SESSION=<session-id>
alpacon exec prod-api-01 -- systemctl restart auth-svc

# 3. Workspace config via 'work-session use' — sticks until you unset it
alpacon work-session use <session-id>
# To clear:
alpacon work-session use --unset
# To inspect:
alpacon work-session current

Resolution priority: --work-session flag > ALPACON_WORK_SESSION env var > workspace config > no session.

4. Complete the session when the change is done.

alpacon work-session complete <session-id>

The session ends, the in-session policy stops applying, and the unified timeline is now exportable as a single audit artifact—the same one the W19 blog post described for human shell sessions, but driven entirely from a terminal. If you need more time mid-flight, alpacon work-session extend <session-id> --expires-in 1h pushes the expiry back.

The MFA-bypass policy

The matching alpacon-web 1.3.15 setting deserves its own paragraph because it's the operator-facing knob that makes session-scoped intent practical for automation.

Per-command MFA prompts are the right default for ad-hoc privileged work. They are not the right default inside an approved session where the purpose, scope, and approver are already on file—automation will get blocked, on-call engineers will start working around the prompts, and you'll end up with a worse audit trail, not a better one.

The new sudo policy setting (PR 1150) lets a workspace admin say: "inside a work session that's been approved for this scope, the declared purpose and approver substitute for a per-command MFA prompt." Outside that session, MFA still fires. The governance signal moves up a level—from "did this command prompt MFA?" to "did this session have declared intent and an approver?"—without losing it.

What this completes

Session-scoped intent is one of the moat pillars Alpacon has been building toward all year. With this release, it's end-to-end across server → console → agent → CLI. The CLI was the last surface where session governance was bypassable; a script could alpacon exec its way through a privileged change and the audit log would capture the commands but not the session boundary. That gap is now closed.

For an SRE running automated remediation, this is the difference between "we have audit logs" and "we have an audit unit." The session is the artifact your auditor asks for—declared purpose, approver, timeline, summary, scope—and your runbook produces it as a side effect of doing the work.

For a CISO in a SOC 2 or HIPAA cycle, the question shifts from "can you reconstruct what happened?" to "show me the session." One screen, one URL, exportable. Including the ones that ran from a terminal.

If you want the longer "why session-scoped intent is the moat" argument, the W19 post is the canonical reference: the W19 work-sessions post. If you want to try the CLI flow, alpacon-cli v1.4.6 is on GitHub (release notes) and the docs are at docs.alpacax.com.

Stop Using SSH Keys in GitHub Actions (Here's What to Use Instead)

AlpacaX — Sat, 11 Oct 2025 00:45:52 +0000

How We Fixed SSH in GitHub Actions (Real Use Cases)

The Problem: SSH in CI/CD Workflows

If you're using GitHub Actions to deploy to your servers, you're probably doing something like this:

- name: Execute remote SSH commands
  uses: <ssh-action>
  with:
    host: ${{ secrets.HOST }}
    username: ${{ secrets.USERNAME }}
    key: ${{ secrets.SSH_PRIVATE_KEY }}
    port: ${{ secrets.PORT }}
    script: |
      cd /app
      git pull
      npm install
      pm2 restart app

This approach has worked for years, but it brings significant security and operational challenges that get worse as your infrastructure grows.

Security Risks

Port 22 Exposed to the Internet

Every server with SSH enabled is under constant attack:

Bots scan for open port 22 thousands of times per day
Automated brute force attempts against your SSH daemon
Zero-day vulnerabilities in SSH daemon itself become attack vectors
Even with fail2ban and strict firewall rules, the attack surface exists

Check your auth logs, you'll see hundreds of failed login attempts from random IPs. That's the reality of exposing SSH to the internet.

Full Server Access with SSH Keys

SSH keys are all-or-nothing:

Grant complete access to the server, no way to restrict which commands can be executed
Read-only operations require the same access level as destructive ones
If a key leaks (committed to git, logged, stolen laptop), attackers have full control
No built-in mechanism to limit what GitHub Actions workflows can do

SSH Keys Scattered Across GitHub Secrets

Managing SSH keys at scale becomes exponential pain:

One SSH key per server: 10 servers = 10 different keys to track
Each repository needs its own copy of these secrets
No centralized view of which keys have access to which servers
Organizational secrets help, but you're still managing one key per server

Operational Pain Points

Key Rotation is a Nightmare

When you need to rotate SSH keys (security incident, compliance requirement, or just good practice):

Generate new key pairs for each server
Update authorized_keys on every server
Update GitHub Secrets in every repository that deploys to those servers
Hope you didn't miss anything
Deal with broken deployments when you inevitably did

For a team with 10 servers and 20 repositories, this is hours of work that nobody wants to do. So keys don't get rotated as often as they should.

No Centralized Audit Trail

When something goes wrong in production:

Logs are scattered across multiple servers
SSH logs show IP addresses (GitHub Actions runners), not which repo/workflow ran what
Manual investigation required: "Who deployed to prod last Tuesday at 3pm?"
No easy way to trace which workflow executed which commands

You end up cross-referencing GitHub Actions logs, SSH auth logs, bash history, and application logs across multiple servers. It's tedious and error-prone.

Per-Repository Secret Management

The same SSH keys get duplicated across repositories:

Update one key → Update it in dozens of places
Revoking access means touching multiple repositories
No fine-grained control over what each repository can do
Junior developer's first deploy has the same access as senior engineer's emergency fix

The Real Cost

These aren't just theoretical concerns. Here's what actually happens:

Security incidents: Leaked SSH keys in git history require emergency rotation across all servers and repos
Broken deployments: Missed secret updates during key rotation cause failed releases at 2am
Compliance failures: Auditors ask "Who ran this command?" and you can't easily answer
Operational overhead: DevOps teams spend hours managing SSH keys instead of building features
Security compromise: Keys don't get rotated because it's too painful, increasing risk over time

And the worst part? This scales badly. Double your servers, and you double your key management burden.

The Solution: Alpacon

Alpacon replaces SSH with API tokens and provides four purpose-built GitHub Actions. Here's what changes:

Authentication:

SSH keys → API tokens
Port 22 exposure → Outbound connection (zero open ports)
Full access → Command-level ACLs

What you gain:

Command ACL (Access Control Lists): Tokens only run commands you explicitly allow, even if leaked, only permitted commands work
Workspace-level token: One token manages multiple servers at once
Automatic audit trail: Know exactly which repo/workflow accessed which server
Flexible token management: Update token permissions or rotate without touching GitHub Secrets
Zero open ports: Outbound connection, servers never listen for incoming connections

How It Works in Detail

1. Command ACL

Unlike SSH keys (which give full access), Alpacon tokens support fine-grained command ACLs.

How it works:
When creating a token, you specify exactly which commands it can execute. Commands with operators (&&, ||, |, >, ;) are blocked. This prevents command chaining or shell injection.

Prevention benefits:
Even if the token leaks, attackers cannot execute unauthorized commands. The token can ONLY run commands you explicitly allowed.

2. Zero Exposed Ports (Outbound Connection)

Alpacon uses a outbound connection model:

Your server initiates an outbound connection to your workspace
No inbound ports opened on your server
Server is not discoverable from the internet

Threats eliminated: SSH port scanning, brute force attacks, direct connection attempts.

3. Centralized Audit Trail

All GitHub Actions activity is automatically tracked:

Operator (user/token) and target server
Exact command executed with full output
File transfers with size and timestamps

Unlike SSH, where logs are scattered across servers, everything is centralized.

4. Simple Token Rotation

Alpacon: Update token in workspace → Update GitHub Secrets once → Done

SSH: Generate keys for each server → Update authorized_keys everywhere → Update Secrets in every repo → Debug failures

Usage: Familiar Workflow, Better Security

Remote Command Execution (alpacon-websh-action)

Execute shell commands on remote servers, deployments, restarts, health checks, anything you'd do over SSH.

- name: Setup Alpacon CLI
  uses: alpacax/alpacon-setup-action@v1.0.0

- name: Deploy application
  uses: alpacax/alpacon-websh-action@v1.1.0
  with:
    workspace-url: ${{ secrets.ALPACON_WORKSPACE_URL }}
    api-token: ${{ secrets.ALPACON_API_TOKEN }}
    target: 'your-server'
    script: |
      cd /app
      git pull
      npm install
      pm2 restart app

- name: Restart system service (with root access)
  uses: alpacax/alpacon-websh-action@v1.1.0
  with:
    workspace-url: ${{ secrets.ALPACON_WORKSPACE_URL }}
    api-token: ${{ secrets.ALPACON_API_TOKEN }}
    target: 'your-server'
    script: systemctl restart nginx
    as-root: true

File Transfer (alpacon-cp-action)

Upload build artifacts, download logs, sync directories, everything you'd use SCP for.

- name: Setup Alpacon CLI
  uses: alpacax/alpacon-setup-action@v1.0.0

# Upload files to server
- name: Upload build artifacts
  uses: alpacax/alpacon-cp-action@v1.1.0
  with:
    workspace-url: ${{ secrets.ALPACON_WORKSPACE_URL }}
    api-token: ${{ secrets.ALPACON_API_TOKEN }}
    source: './dist/'
    target-server: 'prod-server'
    target-path: '/var/www/app/'
    recursive: true

# Download files from server
- name: Download logs for analysis
  uses: alpacax/alpacon-cp-action@v1.1.0
  with:
    workspace-url: ${{ secrets.ALPACON_WORKSPACE_URL }}
    api-token: ${{ secrets.ALPACON_API_TOKEN }}
    source: '/var/log/app/error.log'
    target-server: 'prod-server'
    target-path: './logs/'
    mode: download

Getting Started

Prerequisites: Register Your Servers

Before using these GitHub Actions, you need to register your servers with Alpacon:

Create a workspace at alpacon.io
Install Alpacon agent on your servers using the provided install script
Verify servers are connected in your workspace dashboard

📘 Full guide: Alpacon Documentation - Quickstart

Once your servers are registered and showing as "CONNECTED" in your workspace, you can use them from GitHub Actions.

1. Generate API Token

In your workspace settings, create an API token with appropriate command ACLs.

2. Add Secrets to GitHub

Add these secrets to your repository (or organization for shared access):

ALPACON_WORKSPACE_URL: https://alpacon.io/your-workspace
ALPACON_API_TOKEN: your-token-here

3. Use the Actions

Start with alpacon-setup-action, then add other actions as needed.

The Four Actions

Action	Purpose	Example Use Case
alpacon-setup-action	Install Alpacon CLI	Always run first
alpacon-websh-action	Execute remote commands	Deploy, restart services
alpacon-cp-action	Transfer files	Upload builds, download logs
alpacon-common-action	Run any Alpacon command	List servers, check status

Resources

Conclusion

SSH served us well for 30 years. But modern infrastructure demands modern solutions:

API tokens instead of SSH keys
Command ACLs instead of full access
Audit logs instead of manual investigation
Zero exposed ports instead of internet-facing SSH
Centralized management instead of per-repo configuration

Alpacon GitHub Actions make these benefits accessible in your CI/CD pipelines today.

Try it in your next deployment and see the difference.

Questions of feedback?

We'd love to hear from you in our Discord community.

👉 Join our Discord: [https://discord.gg/wadWh8VsYB]
or drop a comment below!

Want hands-on experience with extra rewards?

We're running a beta testing program where you can explore GitHub Actions integration and earn rewards while helping us improve.

👉 Join the beta: [https://forms.gle/t1rcgXgyPfZewYgF8]

What do you think about the way we still use SSH for server access?

AlpacaX — Mon, 22 Sep 2025 05:52:31 +0000

For decades, SSH has been the default way to access and manage servers.
It works, it’s powerful, and it’s everywhere.
But as our teams and infrastructure grew, we started noticing more and more friction.

Some of the pain points we faced were:

Managing keys and permissions across many users was messy and time-consuming
Simple human errors sometimes caused outages or risky changes
There was no easy way to collaborate in real-time on the same server session
Security concerns grew around credential rotation and temporary access

These experiences made us rethink how server access should work.
That’s why we started building Alpacon, a platform designed to simplify access, improve collaboration, and reduce human mistakes.
Of course, this isn’t a problem only our team faces. Many developers, DevOps engineers, and security teams must have run into the same issues.

So we’re curious: How do you feel about this?

Is SSH still “good enough” for your workflow?
Or do you also feel the need for something new?

We’d love to hear your thoughts and keep this discussion going.

To make it easier, we opened a Discord community where we share ideas about DevOps, security, and infrastructure access.
: https://discord.com/invite/wadWh8VsYB

Looking forward to your perspectives!

discord

AlpacaX — Mon, 22 Sep 2025 05:36:35 +0000