droplet-agent

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #cli #claude-code #codex #developer-tools #react #windows

★ 58 Open GitHub ↗

Droplet Agent is the daemon that runs on customer droplets to enable some features such as web console access.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Droplet Agent is the daemon that runs on DigitalOcean's customer droplets to enable some features such as web console access.

* [Building](#building)
  * [Building From Source Code](#building-from-source-code)
  * [Packaging](#building-from-source-code)
* [Running the Agent](#running-the-agent)
* [Running Tests](#running-tests)
* [Compatibility](#compatibility)
* [Contributing](#contributing)

## Building

### Building From Source Code
Clone this repository:

```bash
> git clone git@github.com:digitalocean/droplet-agent.git
> cd droplet-agent
```

To build the agent, do the following:

1. `cd ./cmd/agent`
2. `GOOS=<target OS> go build -o droplet-agent`

This will generate the `droplet-agent` binary.

Upload that binary to your droplet and run:

`./droplet-agent -debug`

The Droplet Agent should now be running on your droplet.

### Packaging
We now support building `deb` and `rpm` packages. You are welcome to submit
PRs for supporting other package management systems.

NOTES:
1. As of now, the only supported `<target OS>` is Linux, via `deb` and `rpm`
2. The only supported GOARCH is `amd64`
3. `systemd` is required for service management, automatic package updates, and install retries
4. The agent service unit is installed at `/etc/systemd/system/droplet-agent.service`. After editing it, run
`systemctl daemon-reload`
5. Hourly package update checks are handled by `droplet-agent-update.timer` and
`droplet-agent-update.service` in `/etc/systemd/system/`. The timer is enabled automatically on package install.
After editing these units, run `systemctl daemon-reload && systemctl enable --now droplet-agent-update.timer`

## Running the Agent
The agent binary takes several command line arguments:
- `-debug` (boolean), if provided, the agent will run in debug mode with verbose logging. This is useful when debugging.
- `-syslog` (boolean), specify how the log is handled. By default, all logs will be sent to `stdout` and `stderr`, if
`syslog` option is provided, logs will be sent to `syslogd`. When logging to `syslog`, the agent will use `DropletAgent`
as the identifier. To retrieve the logs, simply run `journalctl -t DropletAgent` command.
- `-sshd_port <port>`(integer), explicitly indicates which port sshd binds itself to, so that the agent can properly
monitor the port knocking messages, as well as enabling the web console proxy to connect to the sshd instance. Without
specifying this option, the agent will try parse `sshd_config` to see if custom port is specified by checking the `Port`
and `ListenAddress` entries, if not, it falls to use the default port (22).
- `-sshd_config <path to sshd_config>` (string), explicitly specify the path to the `sshd_config` file. In the cases
that the sshd is started with a custom `sshd_config` file other than the default one (/etc/ssh/sshd_config), this
parameter must be supplied to let the agent function properly

NOTES:
- Be aware that `sshd_port` number has higher priority. The agent will skip attempting to parse the port from
`sshd_config` if `sshd_port` is supplied.
- When parsing the `sshd_config`, the agent will take the first occurrence of port number from either `Port` or
`ListenAddress` entries. If the sshd is configured to bind to multiple interfaces and/or multiple ports, please sepcify
the port number that is exposed externally via `sshd_port` option.

## Running Tests

First, ensure that [Docker](https://www.docker.com) is installed and running.

Then, inside the droplet-agent project directory:

```bash
> go mod vendor
> make test
```

## Compatibility

Droplet Agent currently supports:

- Ubuntu (oldest [End Of Standard Support](https://wiki.ubuntu.com/Releases) LTS release and later)
- Debian ([oldest supported](https://wiki.debian.org/LTS) LTS release and later)
- Fedora 41+
- CentOS 9+
- AlmaLinux 8+
- Rocky Linux 8+

All supported distributions use `systemd`.

## Contributing

Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests.

droplet-agent

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README