CertOne Agent / Getting started

Quick start

Deploy your certificates automatically. Install the agent, connect a node, and let CertOne keep your applications up to date.

The agent connects outbound; no additional inbound port is required. For Docker or Synology containers, follow their guide directly without installing the agent on the host.

Before you start

Have your node ready.

Node ID + Token

Create a deployment node in the platform and obtain its credentials.

Associated certificates

Bind issued certificates to the node. CertOne discovers them automatically.

Use an account that can write certificate files and manage your application. No certificate ID is needed in CertOne settings. Your web server still needs the path for the certificate it serves.

1. Install the agent

One command. The right package for your machine.

AMD64 · ARM64

Shell

sh -c "$(curl -fsSL https://certone.io/downloads/certone/install.sh)"

Then confirm the installation

Shell

certone version

Look for

The version output shows your operating system and architecture.

The installer detects your platform, downloads the matching package, and verifies its SHA256 checksum.

When is sudo needed?

Only when the installer needs permission to write to /usr/local/bin. Downloading and checksum verification do not need sudo. Initialization can run as your regular user.

Installation does not deploy certificates or register a background service. Prefer a user-owned directory or a manual download? See other installation methods.

2. Connect your node

Let the wizard create your configuration.

Shell

certone init

Look for

Your node credentials and deployment settings are saved in config.yaml.

Run the wizard as the account that will run CertOne. Enter the node ID, Token, and deployment type. Keep the default connection settings.

Choose nginx, httpd (Apache), or OpenResty for an existing web server; files only saves certificates. The wizard detects common executable paths, which you should confirm. For IIS or Synology, follow the guide linked above.

Configuration~/.certone/config.yaml

Credential input is hidden, and existing configuration is never overwritten. New node associations are discovered on the next push or synchronization.

Application needs a certificate before it can start?

Keep your application type in the wizard. Run certone sync --once --prepare to write the first certificate files without reloading. Start the application, then run certone sync --once. Follow the initial deployment procedure.

3. Verify and deploy

Check the connection, then make a real deployment.

Point your application's HTTPS configuration at the certificate's actual, absolute file paths. By default, each certificate has its own directory:

~/.certone/certificates/<certificate-id>/fullchain.pem · key.pem

Use the certificate ID shown by doctor --network or the platform. Use your actual absolute home-directory path in application configuration, rather than ~ or %USERPROFILE%. CertOne expands {id} in its templates; your application needs the actual path.

• check validates configuration and local prerequisites.
• doctor --network checks platform authentication and lists available certificate IDs and versions.
• sync --once performs a real deployment and exits.

If a command fails, stop here and follow Troubleshooting before running the next command. Do not run a second deployment while a background instance uses the same state directory.

Verify the application, too

The first two checks do not deploy certificates. Status lists completed targets, certificate versions and output paths. A stopped snapshot after a one-time deployment is normal. Visit the actual HTTPS service to confirm its certificate.

Do not manually reload before the first files are written. Deployment writes the files, validates configuration, then reloads. Protected directories and root-managed applications need appropriate deployment permissions; use an explicit configuration path when elevating privileges.

Check local configuration

Shell

certone check

Check the connection and find certificate IDs

Shell

certone doctor --network

Deploy after the checks pass

Shell

certone sync --once

Inspect the saved deployment status (keep using the same runtime account)

Shell

certone status

Look for

Check the actual HTTPS endpoint to confirm that the expected certificate is active.

4. Keep certificates up to date

Stay connected to receive certificate updates.

Shell

certone run

Look for

Leave this process running. Press Ctrl+C to stop it before installing a background service.

Run in the foreground first and watch the logs. This process receives certificate update notifications and deploys new versions automatically.

Real-time updatesPush notifications trigger synchronization.

Automatic reconnectionNetwork interruptions are retried.

Hourly reconciliationVersion checks recover missed notifications.

Keep the process running

Automatic deployment stops when the process exits. After verifying the first deployment, follow Background Services for continuous operation and startup at boot. Stop the foreground process before starting the service.

An explicit authentication rejection stops retries. Correct the credentials and restart. Read more about how synchronization works.

After setup

Next steps

Advanced usage ↗

Custom paths, commands, and multiple targets.

Troubleshooting ↗

Connection failures, logs, and deployment errors.

Maintenance ↗

Upgrade, rotate credentials, back up, and migrate.

Where are configuration, certificates, and logs stored?

~/.certone/
├── config.yaml
├── certificates/<certificate-id>/
├── state/
└── logs/

Local installations and Docker use the runtime user's home directory. Windows uses %USERPROFILE%\.certone. Directories are created as needed. Docker environment mode does not generate config.yaml and uses container logs by default. The local wizard configures logs/certone.log. Protect configuration and state as sensitive data.