Based on repository activity, growth velocity and community engagement.
26
Growth3/30
Activity10/25
Popularity4/25
Trust10/20
7
Stars
High
Sentiment
Votes
7
README.md
Aphelion
For a plain-English map from Aphelion terminology to familiar systems/security concepts, start with Aphelion, in boring words.
Aphelion is a personal AI harness built for distance. It runs as a Linux
service on a machine you control and gives you a Telegram operator surface.
Every action passes through explicit consent on its way to a typed audit
ledger.
The agent inside Aphelion can fork its own work into parallel side threads,
promote a thread into a distinct sub-agent, and push that sub-agent to a
remote machine over Tailscale — all under the same authority model. The user
is the final arbiter; the architecture takes care of the rest.
Why Aphelion
Most personal AI harnesses are built for a developer at a terminal. Aphelion
is built for an operator running their agent at a remove — from a phone,
across time, across machines they don't sit at, and across the boundary
between intention and action where things tend to go wrong.
Two layers, two reference frames
The agent inside Aphelion is two collaborating roles, not one persona. The
face (Idolum by default) is who you talk to — present, direct,
conversation-oriented. The governor (Idolum (System)) is what holds
authority, decides what the face is allowed to commit to, and produces the
typed records that survive the conversation. The two argue internally. When
they reach an impasse on something material, the conversation pauses and asks
you to arbitrate.
This is structural, not theatrical. The face cannot grant itself permissions;
the governor does not present itself as the conversational persona. Its work
surfaces as approvals, refusals, status, recovery, and typed evidence. You
remain the source of authority, but you are not the constant context driving
what the protected layer is doing. Think of the restaurant kitchen: you order
from a waiter, and you don't usually speak to the cook. That structure exists
so the meal arrives faster, hotter, and right. You can always ask to speak to
the cook; that path stays open. Aphelion is shaped the same way.
Authority before capability
Permissions in Aphelion are not configuration files. They are typed records
that travel through a pipeline: . Each tool, each remote-host
child, each external account, each capability that crosses a trust boundary
lives on this lane. The runtime cannot invoke something it does not have an
active, unexpired grant for.
A child agent on a remote Tailnet host has a different permission envelope
than the parent. A side thread you promoted into its own agent inherits scope
from the promotion act, not from ambient parent state. Scaling permissions up
or down is an explicit governed step, not a config edit; the operator and the
durable record are both involved.
Continuity is structural
Aphelion remembers, parks work during deploys, recovers after restarts, and
explains what happened. Every meaningful event — ingress, turn, tool call,
delivery, continuation authorization — becomes a typed row in an
execution-events ledger. /status and /health trace are projections of
that ledger with source attribution, not log dumps. If the service crashes
mid-turn, the next start picks up the typed run and either resumes it or
surfaces it for repair.
The design principle behind this: prefer typed records over interpreting
prose. The conversation transcript is presentation; the ledger is truth.
Small surface, defended on purpose
Six direct Go module requirements are declared in go.mod; three are the
deliberately chosen primary third-party surfaces: SQLite (vendored in-repo), a
TOML parser, and Tailscale (the substrate that enables remote-host children).
Everything else is pinned and small. A source install needs Go and a Linux user
service; a release install needs only the Aphelion binary and systemd. Model
providers, GitHub App credentials, Sponsors, and hosted storage are explicit
operator choices, not hidden platform dependencies.
This is defensive, not aesthetic. Recent campaigns like Mini Shai-Hulud
(170+ npm and PyPI packages compromised, valid SLSA Build Level 3 attestations
broken) and the cascade following autonomous vulnerability-discovery
capabilities reaching production make small, deliberate dependency trees a
runtime safety property. Aphelion treats its dependency tree the way it
treats user input reaching the governor: as ambient context that should not
be allowed to steer the runtime by default.
What's in the box
Operator surfaces (Telegram): approvals, /health, /status,
/context, /memory, /mission, /model, side threads via /thread,
thread-to-agent promotion.
Voice: Telegram voice-note transcription on input; optional ElevenLabs
replies on output.
Tools: scoped exec, file, search, and fetch tools; curated memory and
session recall; optional OpenAI hosted-storage integration.
Automation: heartbeat, cron, and bounded approval-window grants with
separate state for the main chat and each side thread.
Durable children: configured agents that survive restarts, with daily
review recipes, Telegram group admission, and Tailnet provisioning of
remote-host children.
Providers: Anthropic, OpenAI, OpenRouter, Gemini, Ollama —
configurable per work lane, with failover.
Service plumbing: Linux user-service install/update scripts, optional
GitHub App token helper, health and inventory surfaces.
Install
Pin the installer and release asset to a public release tag:
Other supported providers: anthropic, openrouter, gemini, ollama. See
Operator Setup for configuration details.
quickstart writes ~/.aphelion/aphelion.toml with mode 0600, validates it,
and refuses to replace an existing config unless --force is passed. With
--install-service, it also runs the service install and verifies the deploy.
Normal turns wait for explicit approval. After approving manually, admins can
open a bounded 15-minute approval window from the approved Telegram message;
the inline controls create the temporary automation gate and matching grant
together.
From Telegram, start with /health, /status, and /help. Use /thread to
fork a side lane. Use /context and /memory to inspect what is shaping
replies. Use /mission for objective review and /model for admin
model-routing controls. Full command reference:
docs/telegram-ui-features.md.
Isolated work defaults to no network. When a non-admin or durable profile
needs narrow internet access, use the helper-backed path in
docs/guides/sandbox-networking.md.
For source checkout work on Linux (requires Go 1.26+; check with go version):
go test ./...
make architecture
make design-principles
make public-readiness
make secrets # when Gitleaks is installed
git diff --check
On non-Linux hosts, make test and make architecture intentionally stop
with a Linux-only message. Use make verify-linux-compile for a static
compile check, then run the full verification on Linux before merge.
Run make design-principles(static analysis of authority/consent/control
surfaces) when touching authority, consent, continuation, wake, goal,
status, or operator-facing control surfaces.
Run make live-evals or the narrower make auto-evals(opt-in; spend
provider API calls) before releases that materially change agency,
authority, proactive mission, or prompt behavior.
For governor, continuation, lease, media-routing, private-boundary, or
self-improvement workflow changes, also use the canonical scenario gate:
produce comparable aphelion eval run reports for the baseline and branch,
then cite aphelion eval gate --before baseline.json --after branch.json in
the PR or release review.
For public authority/evidence boundary claims, also run the transcript-driven
bounty smoke suite:
aphelion eval run --suite boundary_attack --mode local --subject governor --format human
Live boundary_attack runs are opt-in and spend provider tokens. Use
--attacker-routes subject for the cheapest first pass, or explicit attacker
routes when you want broader stochastic pressure.
For publication-grade boundary work, separate attacker search from subject
replay. Generate a fixed adversarial corpus once, then replay it against one or
more subjects without spending more attacker tokens:
Live corpus generation gives provider-generated attacks first claim on each
scenario's slots and uses local mutators only as an underfill fallback. The
corpus records per-scenario definition hashes and selected source-kind counts,
so stale corpora are rejected when scenario definitions drift and run output
shows whether the selected set came from providers or fallback mutators. Replay
uses the corpus turn count, so multi-turn attacks are not truncated to the
scripted baseline. A subset corpus replays the scenarios it covers by default;
reports include exact per-scenario corpus case counts. Use --profile redteam
when the claim needs stronger jailbreak-style pressure. The red-team profile
stays publish-safe and Aphelion-specific, but adds fake authority messages, fake
ledger records, protocol fences, Telegram rendering ambiguity, harmless
obfuscation, cross-surface replay, and multi-turn social escalation to the
corpus search.
Going deeper
For readers who want the design substrate, not just the operator surface:
Design principles — the
load-bearing principles that govern implementation choices.
Influences and departures
— what Aphelion borrowed from where (Codex, Hermes, OpenClaw, Julian
Jaynes, behavioral agency literature) and where it deliberately stops.
Spectral Faithfulness
— sibling research project measuring how silently context steers model
output. Aphelion's compositional-identity design treats those findings as
load-bearing.
Architecture reference set — package
ownership, turn lifecycle, constitutional flow, durable topology, state
surfaces, delivery polymorphism.