Open Source

Transparency is not optional.
It's the foundation.

The HostAtlas agent runs on your servers, collects infrastructure data, and communicates with our platform. You deserve to know exactly what it does. That's why the agent is fully open source — every line of code is public, auditable, and buildable from source.

code 100% open source agent license MIT License build Build from source

Why Open Source

Because trust shouldn't require a leap of faith.

The HostAtlas agent runs on your servers. It collects CPU metrics, memory usage, disk stats, network data, service information, and domain configurations. It reads log files. It communicates with our API. Software that does all of that should be open to scrutiny — not hidden behind a compiled binary and a marketing page.

visibility

Full Transparency

Read every line of code the agent executes. See exactly which system files are read, which metrics are collected, how data is serialized, and where it's transmitted. Nothing is hidden. Nothing is obfuscated.

check Every source file on GitHub
check No obfuscated binaries
check Clear, documented codebase
verified_user

Security You Can Verify

Don't take our word for it — verify it yourself. Run your own security audits against the source code. Review every network call. Confirm that communication is outbound-only. Check that no data leaves your server without your knowledge.

check Run your own security audits
check Verify outbound-only communication
check Inspect all network behavior
handshake

Trust Through Openness

We earn trust through transparency, not marketing claims. When we say the agent doesn't send data to third parties, you can verify that claim by reading the source. When we say commands are whitelisted, you can see the whitelist.

check Every claim is verifiable
check No "trust us" required
check Accountability through code
group

Community Contributions

Open source means the community can participate. Report bugs. Suggest improvements. Submit pull requests. The agent gets better because the people who use it help build it. Your expertise makes the tool stronger for everyone.

check Report issues on GitHub
check Submit pull requests
check Shape the roadmap

What You Can Audit

Every layer of the agent is inspectable.

The source code is organized into clear, well-documented packages. Here's exactly what each component does — and how you can verify it yourself.

monitoring

Metric Collection

The collector package reads system metrics from the Linux proc filesystem every 30 seconds. It reads specific, well-defined files — nothing more. You can see exactly which files are opened and what data is extracted.

arrow_right /proc/stat — CPU time counters (user, system, idle, iowait)
arrow_right /proc/meminfo — Total, free, available, buffered, cached memory
arrow_right /proc/loadavg — 1, 5, and 15-minute load averages
arrow_right /proc/net/dev — Network interface bytes received and transmitted
arrow_right /proc/diskstats — Disk read/write bytes and I/O operations
internal/collector/cpu.go
// ReadCPUStats reads /proc/stat and returns CPU counters
func ReadCPUStats() (*CPUStats, error) {
    data, err := os.ReadFile("/proc/stat")
    if err != nil {
        return nil, err
    }
    // Parse first line: cpu user nice system idle ...
    fields := strings.Fields(lines[0])
    return &CPUStats{
        User:   parseUint(fields[1]),
        System: parseUint(fields[3]),
        Idle:   parseUint(fields[4]),
        IOWait: parseUint(fields[5]),
    }, nil
}
cloud_upload

Network Calls

The agent makes outbound HTTPS requests to exactly one endpoint: the HostAtlas API at api.hostatlas.app. There are no other network destinations. No analytics services. No third-party telemetry. No tracking pixels. Every HTTP request is visible in the source.

arrow_right POST /agent/metrics — CPU, memory, disk, network data every 30s
arrow_right POST /agent/discovery — Discovered services, domains, containers every 5min
arrow_right POST /agent/heartbeat — Liveness signal every 15s
arrow_right GET /agent/commands — Poll for whitelisted commands
internal/api/client.go
// PostMetrics sends collected metrics to the HostAtlas API
func (c *Client) PostMetrics(m *Metrics) error {
    payload, _ := json.Marshal(m)
    req, _ := http.NewRequest(
        "POST",
        c.baseURL + "/agent/metrics",
        bytes.NewReader(payload),
    )
    req.Header.Set("Authorization", "Bearer "+c.token)
    req.Header.Set("Content-Type", "application/json")
    resp, err := c.http.Do(req)
    // Only outbound. No listeners. No open ports.
    return err
}
travel_explore

Discovery Logic

The discovery package scans for running services, configured domains, SSL certificates, and containers. It does this by reading process tables, parsing web server configuration files, and querying the Docker socket (if present). Every discovery method is documented and inspectable.

arrow_right Process scanning — Reads /proc/[pid]/cmdline to identify known services
arrow_right Config parsing — Reads nginx/Apache configs to find domains and vhosts
arrow_right Certificate reading — Parses SSL certificate files for expiry dates and SANs
arrow_right Container discovery — Queries Docker API via unix socket for running containers
internal/discovery/services.go
// knownServices defines which processes to detect
var knownServices = []ServiceDef{
    {Name: "nginx",      Binary: "nginx"},
    {Name: "apache2",    Binary: "apache2"},
    {Name: "mysql",      Binary: "mysqld"},
    {Name: "postgresql", Binary: "postgres"},
    {Name: "redis",      Binary: "redis-server"},
    {Name: "caddy",      Binary: "caddy"},
}

// ScanServices checks /proc for known service processes
func ScanServices() ([]Service, error) {
    entries, _ := os.ReadDir("/proc")
    for _, e := range entries {
        cmdline := readFile("/proc/"+e.Name()+"/cmdline")
        // Match against known binaries only
    }
}
terminal

Command Execution

The agent can execute a small set of diagnostic commands requested by the HostAtlas platform (e.g., checking service status or reading specific log lines). Every command must pass through a strict whitelist. Arbitrary shell execution is impossible — the whitelist is hardcoded in the source and cannot be modified at runtime.

arrow_right Hardcoded whitelist — Only predefined commands can be executed
arrow_right No shell interpretation — Commands are exec'd directly, not via sh -c
arrow_right Timeout enforcement — Every command has a maximum execution time
arrow_right Output limits — Response size is capped to prevent memory exhaustion
internal/commander/whitelist.go
// allowedCommands is the exhaustive whitelist
var allowedCommands = map[string]CommandDef{
    "service_status": {
        Cmd:     "systemctl",
        Args:    []string{"is-active", "{service}"},
        Timeout: 5 * time.Second,
    },
    "disk_usage": {
        Cmd:     "df",
        Args:    []string{"-h"},
        Timeout: 5 * time.Second,
    },
    "uptime": {
        Cmd:     "uptime",
        Args:    []string{},
        Timeout: 3 * time.Second,
    },
}

func Execute(name string) (string, error) {
    cmd, ok := allowedCommands[name]
    if !ok {
        return "", ErrCommandNotAllowed
    }
    // Direct exec, no shell interpretation
}
description

Log Access

When log management is enabled, the agent tails specific log files defined in the configuration. It reads only the files you explicitly specify — it never scans for or reads arbitrary log files. Log lines are streamed to the HostAtlas API over TLS and are never written to disk on the agent side.

arrow_right Explicit configuration — Only files listed in agent.yml are tailed
arrow_right No filesystem scanning — No recursive directory walks for log files
arrow_right TLS encrypted transit — All log data is encrypted in transit
arrow_right Rate limiting — Configurable lines-per-second cap to prevent resource exhaustion
/etc/hostatlas/agent.yml
# Log files are opt-in, not auto-detected
logs:
  enabled: true
  paths:
    - /var/log/nginx/access.log
    - /var/log/nginx/error.log
    - /var/log/syslog
  max_lines_per_second: 500
  max_line_length: 4096
build

Build Process

You don't have to trust our pre-built binaries. Clone the repository, read the code, and compile the agent yourself. The build process is a single go build command with no external build dependencies beyond the Go compiler. What you see in the source is what runs on your server.

arrow_right Single binary output — One statically linked executable, no runtime dependencies
arrow_right Reproducible builds — Same source produces the same binary
arrow_right Go modules — All dependencies are pinned in go.sum and auditable
terminal
$ git clone https://github.com/hostatlas/agent.git
$ cd agent
$ go build -o hostatlas-agent ./cmd/agent
Build complete: ./hostatlas-agent (12.4 MB)

$ sha256sum hostatlas-agent
a1b2c3d4e5f6... hostatlas-agent

$ file hostatlas-agent
hostatlas-agent: ELF 64-bit LSB executable,
x86-64, statically linked, Go, not stripped

Repository

The code lives on GitHub.

The entire agent source code is hosted publicly on GitHub. Star it, fork it, clone it, audit it. Here's what you'll find inside.

hostatlas / agent

Public

Open-source infrastructure monitoring agent. Collects metrics, discovers services, monitors domains and certificates. Written in Go.

Go license MIT License star Stars fork_right Forks
folder cmd/ Agent entrypoint and CLI
folder agent/ main.go — binary entrypoint
folder internal/ Core agent packages
folder collector/ CPU, memory, disk, network metrics
folder discovery/ Service, domain, cert, container detection
folder api/ HTTP client for HostAtlas API
folder commander/ Whitelisted command execution
folder config/ YAML configuration parser
folder logger/ Log file tailing and streaming
description go.mod Module and dependency definitions
description go.sum Dependency checksums
description LICENSE MIT License
description README.md Documentation and quickstart
description Makefile Build, test, and lint targets

Clone the repository

$ git clone https://github.com/hostatlas/agent.git_

No Hidden Behavior

What the agent does. And what it absolutely does not.

Clarity about boundaries is just as important as clarity about capabilities. Here's a precise, exhaustive breakdown of the agent's behavior — every item is verifiable in the source code.

check_circle

What the agent does

check

Collect CPU, RAM, disk, and network metrics

Reads from /proc filesystem every 30 seconds

check

Discover running services and their versions

Scans process table for known service binaries

check

Parse web server configurations for domains

Reads nginx/Apache/Caddy config files

check

Read SSL certificates and track expiration

Parses certificate files referenced in web server configs

check

Discover running Docker containers

Queries Docker API via /var/run/docker.sock

check

Report data to the HostAtlas API over HTTPS

Outbound POST requests to api.hostatlas.app, TLS 1.2+

check

Execute whitelisted diagnostic commands

Only predefined commands from a hardcoded list

check

Tail specified log files (when configured)

Only files explicitly listed in agent.yml

cancel

What the agent does not do

close

Send data to third parties

No analytics, no telemetry services, no external endpoints

close

Execute arbitrary commands

Only hardcoded whitelist. No shell interpretation. No user-defined commands.

close

Access user application data

No database queries, no application file reads, no user data access

close

Modify system files or configurations

Read-only access. The agent never writes to system files.

close

Open inbound ports or listen for connections

100% outbound-only. No listening sockets. No open ports.

close

Install additional software or dependencies

Single static binary. No package managers. No downloads at runtime.

close

Collect personal or sensitive user data

No user accounts, no passwords, no environment variables, no secrets

close

Phone home or auto-update without consent

No silent updates. You control when and how the agent is updated.

Build From Source

Don't trust binaries? Build it yourself.

If your security policy requires building software from source, the HostAtlas agent fully supports that workflow. Clone the repository, audit the code, compile it with the Go toolchain, and deploy your own build. The process takes less than a minute.

The agent is written in pure Go with minimal external dependencies. All dependencies are listed in go.mod, and their checksums are locked in go.sum. You can audit every line of every dependency before compiling.

looks_one

Clone the repository

Pull the full source code from GitHub. Every commit is signed and verifiable.

looks_two

Audit the code

Read the source. Review dependencies. Run your security tools against it.

looks_3

Compile with Go

Single go build command produces a static binary. No makefiles, no Docker required.

looks_4

Configure and run

Copy the example config, add your API token, and run as a systemd service.

terminal
# 1. Clone the repository
$ git clone https://github.com/hostatlas/agent.git
$ cd agent

# 2. Review the source (optional but encouraged)
$ find . -name "*.go" | wc -l
47 files

# 3. Build the agent
$ go build -o hostatlas-agent ./cmd/agent
Build successful

# 4. Create configuration
$ sudo mkdir -p /etc/hostatlas
$ sudo cp config.example.yml /etc/hostatlas/agent.yml
$ sudo nano /etc/hostatlas/agent.yml

# 5. Add your API token
api_token: "your-token-here"
api_url:   "https://api.hostatlas.app"

# 6. Install as systemd service
$ sudo cp hostatlas-agent /usr/local/bin/
$ sudo cp deploy/hostatlas-agent.service \
     /etc/systemd/system/
$ sudo systemctl enable --now hostatlas-agent

# 7. Verify it's running
$ sudo systemctl status hostatlas-agent
● hostatlas-agent.service - HostAtlas Agent
   Active: active (running)

Agent Architecture

Five components. One purpose.

The agent is organized into five distinct internal packages, each with a single responsibility. This separation makes the codebase easy to navigate, audit, and contribute to.

speed Collector

Metric Collection

Reads system metrics from /proc every 30 seconds. Collects CPU utilization, memory usage, disk I/O, network throughput, and load averages. Data is buffered locally and batched for efficient transmission.

Package

internal/collector/
schedule Every 30 seconds
travel_explore Discovery

Infrastructure Discovery

Scans for running services, configured domains, SSL certificates, and Docker containers every 5 minutes. Detects changes between scans and reports only deltas to minimize network usage and API load.

Package

internal/discovery/
schedule Every 5 minutes
cloud_upload Reporter

API Communication

Manages all outbound HTTP communication with the HostAtlas API. Handles authentication, request serialization, retry logic with exponential backoff, and connection health checks. All traffic is TLS 1.2+ encrypted.

Package

internal/api/
lock TLS 1.2+ only
terminal Commander

Command Execution

Polls the HostAtlas API for pending diagnostic commands and executes only those that match the hardcoded whitelist. Commands are executed directly (no shell) with enforced timeouts and output size limits.

Package

internal/commander/
shield Whitelist enforced
settings Config

Configuration Management

Parses the YAML configuration file at /etc/hostatlas/agent.yml. Supports API token, endpoint URL, log paths, collection intervals, and feature toggles. All options are documented with sensible defaults.

Package

internal/config/
description /etc/hostatlas/agent.yml
receipt_long Logger

Log Streaming

Tails log files specified in the configuration and streams new lines to the HostAtlas API. Supports file rotation detection, configurable rate limiting, and automatic reconnection. Only reads files you explicitly specify.

Package

internal/logger/
tune Opt-in only

Data flow

Collector Reporter api.hostatlas.app
Discovery Reporter api.hostatlas.app
api.hostatlas.app Commander Whitelist Execute
Logger Reporter api.hostatlas.app

All communication flows through the Reporter. Only one external endpoint exists: api.hostatlas.app over HTTPS.

Contributing

Help us build better infrastructure tooling.

The HostAtlas agent is open source because we believe the best tools are built in the open. Whether you're filing a bug report, suggesting a feature, improving documentation, or submitting a pull request — every contribution makes the agent better for everyone.

We review every issue and PR. We value clear communication, well-tested code, and respectful collaboration. If you're unsure where to start, check the issues tagged good first issue on GitHub.

bug_report

Report Issues

Found a bug? Something not working as expected? Open an issue on GitHub with steps to reproduce. Include your OS, Go version, and agent version. The more detail, the faster we can fix it.

merge

Submit Pull Requests

Fork the repo, create a feature branch, write tests, and open a PR. We follow conventional commits. All PRs must pass CI (linting, tests, build) before review. We aim to review PRs within 48 hours.

shield

Security Disclosures

If you discover a security vulnerability, please report it responsibly. Email security@hostatlas.app with details. Do not open a public issue for security vulnerabilities. We will acknowledge receipt within 24 hours and provide a timeline for a fix.

lightbulb

Suggest Features

Have an idea for improving the agent? Open a feature request issue on GitHub. Describe the use case, the expected behavior, and why it would be valuable. We prioritize features based on community demand and alignment with our roadmap.

Get started

Ready to see your infrastructure clearly?

Start with the free plan. Install the open-source agent on your first server. Auto-discovery begins in seconds and you'll have complete visibility within minutes. Every line of agent code is on GitHub. No credit card required. No sales call needed.

Quick install

$ curl -sSL install.hostatlas.app | bash_