Quick start

Goauld quick start guide

This guide uses three separate machines with the smallest practical configuration:

Server: goauld.example.com, publicly reachable
Client (tealc): the operator workstation
Agent: the target machine, able to reach the server over outbound HTTP on port 80 and outbound TCP on port 2222

Prebuilt client and server binaries are available from the Goauld releases. This guide uses HTTP for the Socket.IO control channel and a direct SSH listener for operational traffic. For an HTTP(S)-only deployment, use the HTTP(S)-only guide.

Generate secrets

Install age, then run:

age-keygen > age-key.txt
cat age-key.txt

Keep age-key.txt private. The server uses the AGE-SECRET-KEY- value; the agent and client use the public age1... value.

Generate access token (and admin token)

openssl rand -base64 42 > access-token.txt
openssl rand -base64 42 > admin-token.txt
chmod 600 age-key.txt access-token.txt admin-token.txt

You now have four values:

age private key → server only
age public key → client and agent build configuration
access token → server and client
admin token → server and client for administrative endpoints

Note

The server, agent, and client all support --generate-config, which writes out a configuration file from the currently-resolved settings (CLI flags, environment variables, etc.). This can be used instead of hand-writing the YAML files shown below.

1. Start the server

A traditional minimal configuration file that exposes HTTP and a direct SSH listener is:

# The server's age private key from age-key.txt.
age-private-key: 'AGE-SECRET-KEY-REPLACE_ME'

# Domains used to serve HTTP and WebSocket traffic.
http-domain:
  - goauld.example.com

# Address and port to bind for HTTP connections (port 0 = random).
http-listen-addr: :80

# Address and port to bind for SSH connections (port 0 = random).
sshd-listen-addr: :2222

# Access token required for the /manage/ API endpoint.
access-token:
  - ACCESS_TOKEN_REPLACE_ME

# Admin token required for the /admin/ API endpoint.
admin-token:
  - ADMIN_TOKEN_REPLACE_ME

# Operator IP addresses allowed to use the management API and SSH.
# Replace with the public IP/CIDR of each operator workstation.
allowed-ips:
  - 203.0.113.10/32

# Disable TLS (minimal example, do not use in production)
tls: false

# Disable the DNS listener (not used in this minimal example)
dns: false

Start the server:

./goauld_server --config-file config.yaml

The server should now be listening on HTTP port 80 for control traffic and SSH port 2222 for operational traffic. Leave this process running.

2. Configure the client on the operator workstation

Place the tealc configuration file in $HOME/.config/tealc.yaml.

# Access token required to access the /manage/ endpoint.
access-token: ACCESS_TOKEN_REPLACE_ME

# HTTP Server to connect to.
server: http://goauld.example.com

# SSH Server to connect to.
ssh-server: goauld.example.com:2222

# Agent age public key. Only consumed by `tealc compile` when generating agents.
age-public-key: age1PUBLIC_KEY_REPLACE_ME

# Used by administrative commands such as agent deletion.
admin-token: ADMIN_TOKEN_REPLACE_ME

Note

age-public-key is used only by tealc compile. Instead of tealc.yaml, you can pass it per build with -K/--age-public-key (or TEALC_AGE_PUBLIC_KEY), or bake it into a build file as AGENT__AGE_PUBLIC_KEY (which is what the next section does).

3. Build and start the agent

On the operator workstation, generate an environment file and set the values that match the server:

Generate the configuration file:

tealc compile --drop-env > ./env.txt

Update the configuration file according to your setup

Minimal file with only HTTP (and SSHD) enabled:

# Public age key corresponding to the server's private key
AGENT__AGE_PUBLIC_KEY=age1PUBLIC_KEY_REPLACE_ME
# HTTP host
HTTP_DOMAIN=goauld.example.com
# SSHD port exposed by the server
SSHD_PORT=2222
# HTTP Port
HTTP_PORT=80

Compile the agent using the generated configuration file:

tealc compile --env ./env.txt --id agent --goarch amd64 --goos windows

The compiled agent will be located in the folder output/agent/ (e.g.: output/agent/goauld_windows-amd64.exe)

See Compile agent for more compilation options.

Once the compiled agent is on the target machine, start it:

.\goauld_windows-amd64.exe

The agent should appear in tealc tui within a few seconds.

Note

--background/-B runs the agent as a detached background process instead of in the foreground.

For transport selection and working-hour restrictions, see the agent guides.

4. Connect to the agent

Using the TUI

tealc tui

Select the agent and press Enter.

Using the CLI

tealc ssh [AGENT_NAME]

AGENT_NAME is normally [USERNAME]@[HOSTNAME]. It can be changed with --name or AGENT__NAME; see agent variables.

Verify the setup

If the agent does not appear, run:

tealc list
curl -I http://goauld.example.com/
nc -vz goauld.example.com 2222

Then consult troubleshooting.