Getting Started with the Logship Agent

This tutorial walks you through setting up a Logship agent that collects system metrics and ships them to your Logship instance. By the end, you'll have an agent collecting disk, network, and process data from your host.

Prerequisites

• A running Logship instance (e.g. https://logship.example.com)
• An account on the Logship instance with agent management permissions
• Docker (for container deployment) or a supported OS for native installation

Step 1: Find Your Account ID

You'll need your account ID (a GUID) for the agent configuration.

1. In the Logship frontend, navigate to your account settings.
2. Copy the Account ID displayed on the page.

Step 2: Configure the Agent

Create an appsettings.json file with your Logship endpoint and account ID:

{
  "Output": {
    "endpoint": "https://logship.example.com",
    "account": "YOUR-ACCOUNT-ID-HERE",
    "interval": "00:00:05",
    "maximumBufferSize": 20000,
    "maximumFlushSize": 5000
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  },
  "Sources": {
    "DiskInformation": {
      "enabled": true,
      "interval": "00:00:30"
    },
    "SystemInformation": {
      "enabled": true,
      "interval": "01:00:00"
    },
    "NetworkInformation": {
      "enabled": true,
      "interval": "00:00:30"
    },
    "ProcessInformation": {
      "enabled": true,
      "interval": "00:01:00"
    },
    "Internals": {
      "enabled": true,
      "interval": "00:00:30"
    }
  }
}

Replace YOUR-ACCOUNT-ID-HERE with the account ID from the previous step.

What this configuration collects

Source	What it does	Interval
DiskInformation	Disk usage and filesystem stats	Every 30 seconds
SystemInformation	OS version, hostname, hardware info	Every hour
NetworkInformation	Network interface statistics	Every 30 seconds
ProcessInformation	Running process list and resource usage	Every minute
Internals	Agent self-monitoring metrics	Every 30 seconds

Step 3: Deploy the Agent

Option A: Docker (recommended)

docker run -d --name logship-agent \
  --network host \
  --restart unless-stopped \
  -v $PWD/appsettings.json:/app/appsettings.json:ro \
  ghcr.io/logship-io/logship-agent:latest

Verify the agent is running:

docker logs logship-agent

You should see log output indicating the agent has started and is waiting for approval.

Option B: Native (Linux)

1. Download the latest release from GitHub Releases.
2. Extract and place appsettings.json alongside the binary.
3. Run:

./logship-agent

Option C: Windows Service

1. Download the latest Windows ZIP release from GitHub Releases.
2. Extract and place appsettings.json in the same directory.
3. Install and start the service:

.\logship-agent.exe install --config "C:\logship\appsettings.json"
.\logship-agent.exe start

Step 4: Approve the Agent

When the agent starts without a registration token, it registers itself with the Logship backend and polls for approval. You need to approve it from the frontend before it can send data.

1. Log in to the Logship frontend.
2. Navigate to Agents from the account settings menu.
3. The new agent will appear under Pending Approvals, identified by its hostname.
4. Click Approve to authorize the agent.

The agent automatically detects the approval and begins sending data — no restart required.

Step 5: Verify Data in Logship

Once the agent is approved, data will begin flowing within seconds.

1. Open the Logship frontend and navigate to the Query page.
2. Run a query to confirm data is arriving:

logship.agent.health
| take 10

You should see recent health records from your agent. Try exploring the other tables created by your configured sources:

logship.disk
| take 10

logship.network
| take 10

Pre-Approved Agents with Registration Tokens

For automated deployments where manual approval isn't practical — such as Kubernetes, auto-scaling groups, or CI/CD pipelines — you can pre-approve agents using a registration token. Agents configured with a token are automatically approved on first connection.

Creating a registration token

1. In the Logship frontend, navigate to Agents.
2. Click Create Registration Token.
3. Choose an expiration period (e.g. 30 days or 1 year).
4. Copy the generated token.

Using the token

Add a registration section to your appsettings.json:

{
  "Output": {
    "endpoint": "https://logship.example.com",
    "account": "YOUR-ACCOUNT-ID-HERE",
    "registration": {
      "registrationToken": "YOUR-REGISTRATION-TOKEN-HERE"
    }
  },
  "Sources": {
    "DiskInformation": {
      "enabled": true,
      "interval": "00:00:30"
    }
  }
}

The agent will authenticate and begin sending data immediately — no manual approval step is needed.

Adding More Sources

Once your baseline agent is running, you can enable additional sources by adding them to the Sources section. See the full Configuration Reference for all available sources.

For example, to add log file tailing:

{
  "Sources": {
    "LogFile": {
      "enabled": true,
      "include": ["*.log"],
      "workingDirectory": "/var/log/myapp/",
      "encoding": "utf-8"
    }
  }
}

Or to receive OpenTelemetry data over gRPC:

{
  "Sources": {
    "Otlp": {
      "enabled": true,
      "port": 4317
    }
  }
}

Next Steps

• Configuration Reference — Full documentation for all sources and settings.
• Install — Platform-specific installation details.