Decisions
This page lists decisions that have been made along the way of making IO. If you’ve heard of Architectural Decision Records, you know what this is about. For more background, see this decision.
Decisions are linked on Bluesky by @agent.io. Reply there to comment here.
Build an AT Protocol PDS
·211 words·1 min
AT Protocol
Build an AT Protocol PDS the hard way (from scratch).
Distribute MacOS builds with Homebrew
·8 words·1 min
Distribution
IO
MacOS
Distribute IO builds for MacOS using Homebrew.
Debian packages
·8 words·1 min
Distribution
IO
Debian
Build and distribute IO in Debian packages.
Add MacOS support
·253 words·2 mins
Distribution
IO
MacOS
Get IO working on Macs.
Conform to the XDG Base Directory Specification
·378 words·2 mins
IO
Config
Store IO state and temporary files in standard locations.
Build Envoy and IO containers directly
·75 words·1 min
Docker
Distribution
Use gcr.io/distroless and self-built Envoys to have more control and to reduce dependencies, vulnerabilites, and image size.
Use CGO, libc, and pure SQLite
·339 words·2 mins
IO
SQLite
Envoy
Alpine
Since Envoy will always depend on libc, it seems reasonable for IO to also.
Use the Charm logger
·28 words·1 min
Logging
IO
Use the Charm logger consistently through IO.
Hold on Alpine Linux
·697 words·4 mins
Linux
Alpine
I love the ideas behind this lightweight distribution, but it’s challenging in practice.
Build and Use Sidecar
·298 words·2 mins
Coding
GRPC
Connect RPC
Sidecar
Replace Connect with a new, simple, transparent Go gRPC library.
Drop Service Infrastructure
·509 words·3 mins
APIM
Google
Remove and abandon integration with Google’s Service Infrastructure APIs.
Use one JWT library
·64 words·1 min
Quality
IO
Identity
Use github.com/lestrrat-go/jwx/v3 for all JWT operations.
Minimize Dependencies
·134 words·1 min
Quality
IO
Keep third-party dependencies at a minimum.
No SDKs
·158 words·1 min
Quality
IO
No third-party SDKs are used by IO to call networked APIs.
Use a Custom Fleet Manager
·162 words·1 min
Config
Manage node configurations with Go and ssh.
Use OpenTelemetry
·758 words·4 mins
Telemetry
Analytics
Use OpenTelemetry and Grafana for metrics, logging, and tracing.
Use Distroless Envoy images
·123 words·1 min
Docker
Distribution
Reduce dependencies, vulnerabilites, and image size.
Record Decisions
·118 words·1 min
Process
Keep a record of significant decisions that have been made or are in progress.
Use DockerHub
·61 words·1 min
Distribution
Services
Docker
Use DockerHub for container distribution.
Use SCP and SFTP
·88 words·1 min
IO
SSH
Config
Use SCP and SFTP to configure and observe IO.
Use SSH to connect to IO
·87 words·1 min
IO
SSH
Use SSH to make the IO TUI available to remote users.
Use DigitalOcean
·55 words·1 min
Operations
Services
Prefer DigitalOcean for online operations and examples.
Use Google Workspace
·26 words·1 min
Services
Use Google Workspace to host agent.io email and docs.
Release a Private Preview
·110 words·1 min
Process
Licensing
Telemetry
Initially release IO in a licensed private preview with telemetry.
Use Vault
·96 words·1 min
Secrets
Operations
IO
Vault
Build Vault integration and use Vault to manage secrets.
Internalize Protobuf Codegen
·118 words·1 min
Coding
IO
All protobuf support code that IO uses is generated within the project.
Evaluate Zig
·150 words·1 min
Coding
Languages
Consider using Zig for future projects that call for high performance with limited dependencies.
Build AT Protocol OAuth Support
·105 words·1 min
OAuth
AT Protocol
IO
Build support for AT Protocol Authorization directly into IO.
Build OAuth Support
·94 words·1 min
IO
OAuth
Build support for OAuth into IO.
Use Nomad
·76 words·1 min
Operations
IO
Nomad
Build Nomad integration and use Nomad to manage containers.
Use HCL
·94 words·1 min
Coding
Languages
Config
IO
Configure IO with the Hashicorp Configuration Language.
Build ACME Support
·83 words·1 min
IO
Build support for the ACME protocol into IO to automatically provision SSL certificates.
Use Hugo
·133 words·1 min
Web
Go
Use Hugo and Blowfish to build web sites.
Use App Engine
·188 words·1 min
Services
Operations
Use Google App Engine, but minimally, focusing on static site publication with minimal backend automation.
Use SQLite
·94 words·1 min
IO
Use SQLite for IO internal storage and general data persistence.
Use Bubble Tea
·79 words·1 min
Coding
Go
IO
Config
Use Bubble Tea to build a terminal user interface for IO.
Use Connect RPC
·95 words·1 min
Coding
GRPC
Connect RPC
Use Connect RPC instead of Google’s Go gRPC library.
Name the proxy "IO"
·41 words·1 min
Agent IO
IO
Use “IO” to clearly describe the project’s goals.
Use Linux Abstract Sockets
·58 words·1 min
Coding
IO
Use Linux Abstract Sockets for local communication.
Build an Envoy Controller
·85 words·1 min
IO
IO is an Envoy controller and Envoy is a core component of IO.
Avoid Rust
·260 words·2 mins
Coding
Languages
Hold on Rust investigations. Rust doesn’t seem to be a good fit for our current needs and practices.
Document Service Infrastructure
·79 words·1 min
Web
Thoroughly explain and evaluate the Service Infrastructure APIs.
Develop in Go
·97 words·1 min
Coding
Languages
Go
Use Go for all significant code development.
Use the agentio GitHub organization
·91 words·1 min
Distribution
Keep all Agent IO code in the agentio org on GitHub.
Scope the Project
·87 words·1 min
Process
Build something for developers that makes it easier and safer to work with APIs.
Use the agent.io domain
·121 words·1 min
Distribution
Agent IO
Use the agent.io domain for Agent IO.
Use GitHub
·132 words·1 min
Distribution
Services
Use GitHub for source code management and a few lifecycle-related tasks.