BotreamDocs
Website Türkçe v0.1.1

Quick start

This walkthrough takes you from a fresh installation to a first finished run: you sign in, check that an agent is online, build a small web task, run it and read its log.

Before you start

You need:

Tip: For your first task, build and run on the same computer. Element capture always works through the agent on the computer where your browser is, and the messagebox command in this example opens on the agent's screen.

1. Sign in

Open the web app at http://<server-name>:<port> (port 3000 unless your administrator chose another one), enter your Username and Password and click Sign in.

You land on the Dashboard. The Agents online figure and the Agents card show which robots are connected right now.

2. Check that the agent is online

On the agent computer, the Botream Agent icon sits in the notification area. Hover over it: the tooltip should read Botream Agent · Connected. Clicking the icon opens the agent's dashboard with the server, the agent name and its recent runs.

Tooltip / status What to do
Connected Nothing, you are ready.
Waiting for administrator approval An administrator approves the agent under Administration → Agents (Approve).
Refused: … The server address or registration token is wrong, or the agent was rejected or deactivated. See Install agents.
Disconnected, retrying The server cannot be reached. Check the address and the network.

Administrators also see every agent, its status and its version under Administration → Agents.

3. Create a task

  1. In the sidebar, open Tasks.
  2. Stay in the Local view. Local is your own workspace: new tasks start here and nobody else sees them until you push them. Public shows the pushed versions that schedules and other users run.
  3. Optionally select a folder on the left; the task is created in it.
  4. Click New task, keep Blank task, enter a Name (for example Quick start) and click Create and open.

The New task dialog can also start the task from a ready-made template (From a template) or open it with the AI Task Generator (Describe it to AI); see Start from a template below.

The editor opens. The toolbar shows the task name with the tag Local · never pushed.

The editor has three panels:

  • Left: COMMANDS (the command palette, with Search commands) and VARIABLES.
  • Centre: the task, as Blocks or as Code (the task language as text). Both views show the same task.
  • Right: PROPERTIES of the selected command.

See The task editor for everything the editor can do.

4. Add the commands

The task opens a web page, reads its heading, writes it to the log and shows it in a message box.

Open the browser

  1. In COMMANDS, search for browser and click Browser (or drag it into the task).
  2. In PROPERTIES, set Action to open, URL to https://example.com and Output to page.

The Output variable page is how later commands refer to this browser.

Read the heading with Capture

  1. Open https://example.com in a Chrome tab on your computer. Capture picks the element in your own browser, not in the one the task opens.
  2. Add a Capture command. Set Action to gettext, Browser to $page$ and Output to heading.
  3. Click Capture next to Selector. The dialog says Switch to Chrome and click the element.
  4. Switch to the Chrome tab. Elements are highlighted as you move the mouse; click the heading Example Domain. The click does not reach the page, and Esc cancels.
  5. Back in the editor, if several ways to find the element were found, pick one (the first is marked Recommended) and click Use selected.

Selector is now filled in. If several agents are online, the dialog first asks you to choose the one on this computer.

Note: Capture needs the Botream Agent tray app on this computer and the Botream Element Capture extension in Chrome. If the dialog reports a problem, see Install the browser extension.

Log and show the result

  1. Add a Log command with Message The heading is: $heading$.
  2. Add a Message box command with Title Quick start and Message The page heading is: $heading$.

Type $ in a field, or use its variable button, to insert a variable.

The same task as code

Switch the centre panel to Code to see the task in the task language. You can also type or paste it there instead of building it block by block:

browser --action:open --url:"https://example.com" --output:page
capture --browser:$page$ --action:gettext --dompath:"//h1" --output:heading
log --message:"The heading is: $heading$"
messagebox --title:"Quick start" --message:"The page heading is: $heading$"

Your Selector may differ from //h1: it is whatever you chose in the capture dialog. The language is described in The task language; every command and parameter is in the command reference, for example browser, capture, log and messagebox.

5. Save

Click Save (or press Ctrl+S). The message Saved to your local copy confirms it.

Saving writes your local copy only; it does not create a version. While a required field is empty or a line has an error, the toolbar shows To complete or Problems instead of No problems and saving is blocked. Click the indicator to jump to the command concerned.

6. Run

  1. Click Run in the toolbar. Run is disabled while you have unsaved changes: agents run the saved local copy.
  2. In the dialog, keep Any available agent or choose your agent under Agent, then click Run.

While the task runs, the page shows Running Quick start with the agent's name and the elapsed time. On the agent computer:

  • a browser opens https://example.com,
  • a small progress panel shows the current command,
  • the message box appears. The run waits until you click OK, so switch to it and confirm.

When the task ends, a notification reports Quick start completed (or failed, with the error). Cancel in the running card stops the task on the agent.

7. Read the execution log

Click Watch the live log while the task runs, or open Executions in the sidebar and click the run.

The execution page shows the agent, start time, duration, who started it and the inputs and outputs, then the log. Filter it by level (Info +, Warnings, Errors, Debug) or search it; Follow keeps the newest line in view while a run is live. Your Log line The heading is: Example Domain is there.

If a run fails, the page also shows the failing line, a screenshot of the agent's screen and the variables at that moment. See Running tasks and Debugging.

8. Push the task

Your task exists only in your local workspace. To publish it, so that schedules and other users can run it:

  1. Click Push in the editor toolbar.
  2. Optionally describe the change under What changed?.
  3. Click Push as version 1.

The task becomes public as version 1. Later, to change a public task, you Pull it (which locks it for others), edit and save your local copy, and push it again as the next version. See Versions and workspaces.

Start from a template

You do not have to start from an empty page. Botream comes with templates: complete, commented tasks for common jobs that you adapt instead of building from scratch.

Template What it does
Save PDF attachments of unread e-mails Reads unread e-mails with attachments (mail read), saves their PDF files into a folder and marks the e-mails as read.
Type Excel rows into a web form Reads a sheet (excel readrange) and fills in a web form for every row.
Extract invoice fields from PDFs with AI Reads every PDF in a folder with ai extract and writes the fields into an Excel report.
Copy a web page table into Excel Reads an HTML table (capture gettable) and writes it into an Excel file.
Monthly sales summary from Excel Reads a sales sheet, calculates every row's revenue with a formula (datatable addcolumn), totals it per region (groupby) and writes the summary and the grand total (aggregate) into an Excel report.
Collect search results from several pages into Excel Reads every search result page after page with the Extract data wizard (capture extract) and writes them into an Excel file.
Process work queue items Takes the items of a work queue one at a time, completing or failing each one in a try/catch.
Daily report e-mail about yesterday Works out yesterday's date (datetime), finds that day's report files and sends a summary e-mail.
Archive files older than N days Moves the files of a folder that have not changed for a number of days into an archive folder.
Ask for approval of a large amount Asks a person in the Inbox (humantask) to approve a payment above a limit.

To use one:

  1. Click New task on the Tasks page and choose From a template, or click Start from a template in an empty task.
  2. Filter the cards by category (Email, Excel & data, Web, Documents & AI, Files, Work queues, Approvals) and click a template. The right side shows To fill in before the first run and a preview of its Blocks or Code.
  3. In the dialog, click Create and open (the name and description are filled in from the template and can be changed). In the editor, click Use template or double-click the card; the commands replace the empty task, and Ctrl+Z takes them back.

Then fill in what the template needs:

  • Inputs: folders, files, addresses and limits are input declarations with example defaults at the top of the task. Change the defaults, or give the values when you run or schedule the task.
  • Accounts: mail blocks name the vault Mail and the credential Robot mailbox. Choose your own vault and credential in the properties of each mail block (see Vaults), and the mail server of your provider.
  • Elements: a comment starting with CAPTURE THIS stands before every web step whose element you must pick. Select the step under it and click Capture in its properties: the selector in the template is only an example.

The empty task also offers Generate with AI, which opens the AI Task Generator, and three tips: drag commands from the palette or press Ctrl+K, capture elements with the Capture button, and debug step by step with breakpoints (F9).

Next steps

Botream 0.1.1 · Generated 2026-10-14