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

Step 3: Deploy the Agent

Docker

docker pull ghcr.io/logship-io/logship-agent:latest
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.

Linux

1. Download the latest release from GitHub Releases.
2. Extract the ZIP and place appsettings.json alongside Logship.Agent.ConsoleHost.
3. Run:

./Logship.Agent.ConsoleHost

Windows Service

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

New-Service -Name "logship.agent" -BinaryPathName "C:\logship\Logship.Agent.ConsoleHost.exe" -DisplayName "Logship Agent" -StartupType Automatic
Start-Service -Name "logship.agent"

Step 4: Approve the Agent

When the agent starts without a registration token, it registers itself with the Logship backend and waits for approval. You need to approve it in logship 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.

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.uptime
| take 10

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

System.Storage
| take 10

System.Network.Interfaces
| 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
    }
  }
}

For Linux security monitoring, you can enable normalized auth events, SSH posture, and persistence inventory:

{
  "Sources": {
    "Linux.AuthEvents": {
      "enabled": true,
      "interval": "00:00:15"
    },
    "Linux.SshPosture": {
      "enabled": true,
      "interval": "00:05:00"
    },
    "Linux.PersistenceInventory": {
      "enabled": true,
      "interval": "00:05:00"
    }
  }
}

Docker monitoring is also available through Linux.Docker, but it is disabled by default because access to /var/run/docker.sock is highly privileged.

Next Steps

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