Give users access to Knowledge Worker Agent

Last published : Nov 09, 2026
This guide shows you how to add Knowledge Worker Agent to a workspace's access items, so users can open it with one click.
Knowledge Worker Agent runs as a service inside the workspace. SecurSpaces starts it and makes its port available through a custom access item. Without one, Knowledge Worker Agent isn't started, and users can't reach it.
Related information
Administer Knowledge Worker Agent

Before you start

You need:
  • A workspace image that contains Knowledge Worker Agent, at /usr/bin/knowledge-worker-agent. This is the case for the Knowledge Worker Agent image, and for your own image if you copy the binary into it. See Add Knowledge Worker Agent to your own workspace image.
  • Permission to edit the workspace, or the workspace template it's created from.
  • The icon for the access item, if you want one. The Knowledge Worker Agent repository has it in its Assets folder, as icon-512.png, icon-192.png, and icon.svg.

Add the access item

Add it to the workspace template, so every workspace created from the template has it. To give access to one workspace only, add it to that workspace instead.
  1. Open the workspace template, or the workspace, for editing.
  2. In the Basic Info step, find Workspace Access, and add a custom access item.
  3. Fill in the fields:
    Field Value Notes
    Name Chat, or another name Required. Shown on the access button.
    Icon icon-512.png from the Assets folder Optional. Select Upload, and choose the file.
    Command /usr/bin/knowledge-worker-agent Required. Starts Knowledge Worker Agent.
    Open Port 8765 Required. Must match KWA_PORT, if you set it.
    Health Probe Leave empty
    Health Timeout 0
  4. Save the access item, then save the workspace or template.
Edit Custom Access Item dialog
Images built before the binary was renamed have it at /usr/bin/chat. Current images keep /usr/bin/chat as a link to the binary, so an access item that uses it still works.
Names and ports must be unique within a workspace. The port can't be one the platform reserves for its own services. For the other options of custom access items, see Custom access items.

Check that it works

  1. Start a workspace from the template, or restart the workspace you edited.
  2. Select the access item.
Knowledge Worker Agent opens. The first time, chats may take a few seconds to become available while it prepares opencode.
If the access item is missing, it isn't on that workspace or its template. If it's there but doesn't open, check that Open Port matches KWA_PORT. For more checks, see Troubleshoot Knowledge Worker Agent.