README
¶
GoHome
GoHome is a self-hosted home automation platform. gohomed runs on your local network and connects to devices via a driver model; gohome is the CLI for managing it.
Modules
| Module | Path | Description |
|---|---|---|
github.com/fdatoo/gohome |
. |
Daemon (gohomed) + CLI (gohome) |
github.com/fdatoo/gohome-driverkit |
./gohome-driverkit |
SDK for building device drivers |
Both modules are linked by a Go workspace (go.work), so go build ./... and go test ./... work across the full tree from the repo root.
Prerequisites
- Go 1.25+
- Task —
brew install go-task - buf —
brew install bufbuild/buf/buf(proto codegen) - Pkl —
brew install pkl(config schema) - Node.js 20+ — for the web UI
Building
task build # builds gohomed + gohome binaries into dist/
task web:build # builds the web UI (required before task build)
Testing
task test # unit tests
task test:race # race detector
task test:integration # integration tests (real disk I/O)
Drivers
Drivers are out-of-process binaries that implement the driver gRPC protocol. Use the gohome-driverkit to build one:
cd gohome-driverkit
go build ./...
Documentation
Full documentation lives in docs/ and is published via Zensical. Design specs and implementation plans live in docs/design/.
License
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
gohome
command
|
|
|
gohomed
command
|
|
|
testdriver
command
Package main is a minimal scenario-driven driver binary used by integration tests.
|
Package main is a minimal scenario-driven driver binary used by integration tests. |
|
gen
|
|
|
internal
|
|
|
api
Package api provides shared helpers for the Connect-RPC API layer, including error mapping, pagination, and time conversion utilities.
|
Package api provides shared helpers for the Connect-RPC API layer, including error mapping, pagination, and time conversion utilities. |
|
auth/audit
Package audit emits AuthEvent payloads to the event store.
|
Package audit emits AuthEvent payloads to the event store. |
|
auth/migrations
Package migrations embeds auth SQL migrations for goose.
|
Package migrations embeds auth SQL migrations for goose. |
|
auth/sessions
Package sessions stores cookie-based browser sessions with HMAC-signed access cookies and rotating refresh cookies.
|
Package sessions stores cookie-based browser sessions with HMAC-signed access cookies and rotating refresh cookies. |
|
auth/throttle
Package throttle implements a soft per-IP × per-method failed-auth throttle.
|
Package throttle implements a soft per-IP × per-method failed-auth throttle. |
|
automation
Package automation is the runtime engine.
|
Package automation is the runtime engine. |
|
automation/action
Package action owns automation-engine action executors.
|
Package action owns automation-engine action executors. |
|
automation/condition
Package condition holds automation-engine condition evaluators.
|
Package condition holds automation-engine condition evaluators. |
|
automation/testutil
Package testutil provides fakes for automation engine tests.
|
Package testutil provides fakes for automation engine tests. |
|
automation/trigger
Package trigger defines the runtime trigger-matching surface.
|
Package trigger defines the runtime trigger-matching surface. |
|
carport
Package carport hosts the driver-supervisor subsystem: drivers.toml configuration, per-instance subprocess lifecycle, command dispatch, and event ingest from drivers over the Carport gRPC protocol (v1alpha1).
|
Package carport hosts the driver-supervisor subsystem: drivers.toml configuration, per-instance subprocess lifecycle, command dispatch, and event ingest from drivers over the Carport gRPC protocol (v1alpha1). |
|
carport/fakedriver
Package fakedriver provides an in-process implementation of the Carport Driver gRPC service used by unit tests.
|
Package fakedriver provides an in-process implementation of the Carport Driver gRPC service used by unit tests. |
|
cause
Package cause provides a context key for threading automation correlation information through call chains.
|
Package cause provides a context key for threading automation correlation information through call chains. |
|
cli
Package cli owns the gohome CLI command tree, styling, and output helpers.
|
Package cli owns the gohome CLI command tree, styling, and output helpers. |
|
daemon
Package daemon wires the eventstore, state cache, registry, CLI socket, and observability into a single runnable gohomed.
|
Package daemon wires the eventstore, state cache, registry, CLI socket, and observability into a single runnable gohomed. |
|
eventstore
Package eventstore owns the SQLite event log, tailer, projector dispatch, subscriptions, and snapshots.
|
Package eventstore owns the SQLite event log, tailer, projector dispatch, subscriptions, and snapshots. |
|
eventstore/eventstoretest
Package eventstoretest provides a fake in-memory Appender for unit tests.
|
Package eventstoretest provides a fake in-memory Appender for unit tests. |
|
mcp
Package mcp implements the gohome MCP server (stdio transport).
|
Package mcp implements the gohome MCP server (stdio transport). |
|
mcp/audit
Package audit emits MCP audit events through the daemon RPC surface.
|
Package audit emits MCP audit events through the daemon RPC surface. |
|
mcp/fs
Package fs provides MCP filesystem-tool helpers.
|
Package fs provides MCP filesystem-tool helpers. |
|
mcp/resources
Package resources registers gohome MCP resource handlers for entity state and automation traces, including live-subscription support.
|
Package resources registers gohome MCP resource handlers for entity state and automation traces, including live-subscription support. |
|
mcp/tools
Package tools registers all gohome MCP tools.
|
Package tools registers all gohome MCP tools. |
|
observability
Package observability owns logging, metrics, and tracing setup.
|
Package observability owns logging, metrics, and tracing setup. |
|
policy
Package policy compiles Pkl-declared policies into a runtime artifact and evaluates Authorize requests against it.
|
Package policy compiles Pkl-declared policies into a runtime artifact and evaluates Authorize requests against it. |
|
registry
Package registry owns the SQL-backed projection of driver instances, devices, entities, and durable event subscriptions.
|
Package registry owns the SQL-backed projection of driver instances, devices, entities, and durable event subscriptions. |
|
script
Package script provides the runtime for invocable named Starlark functions.
|
Package script provides the runtime for invocable named Starlark functions. |
|
script/testutil
Package testutil provides synthesized helpers for testing the script engine without going through Pkl compile or a full daemon.
|
Package testutil provides synthesized helpers for testing the script engine without going through Pkl compile or a full daemon. |
|
starlark/testutil
Package testutil provides a pre-wired Runtime with injectable fakes for use in Go tests (primarily C6 automation/condition unit tests).
|
Package testutil provides a pre-wired Runtime with injectable fakes for use in Go tests (primarily C6 automation/condition unit tests). |
|
state
Package state owns the in-memory copy-on-write cache of entity state.
|
Package state owns the in-memory copy-on-write cache of entity state. |
|
storage
Package storage owns SQLite open/PRAGMA/migration plumbing and the minimal Tx interface projectors use.
|
Package storage owns SQLite open/PRAGMA/migration plumbing and the minimal Tx interface projectors use. |
|
storage/migrations
Package migrations embeds eventstore SQL migrations for goose.
|
Package migrations embeds eventstore SQL migrations for goose. |
|
testutil
Package testutil offers shared helpers: in-memory DB, event builders, fixture loading.
|
Package testutil offers shared helpers: in-memory DB, event builders, fixture loading. |
Click to show internal directories.
Click to hide internal directories.