Skip to content

TaskVine Quickstart

In this exercise, you will start a TaskVine manager, observe it waiting for execution resources, and connect one local worker from a second terminal.

The prepared program submits five word-count tasks. Each task runs the Linux tools grep and wc to search for a different word in the same copy of War and Peace.

This quickstart uses vine.Task, TaskVine's standard command-task interface. A standard task describes a Unix command line. The later matrix exercises use vine.PythonTask to execute Python functions instead.

Before you begin

Complete Access and Setup before starting. Both setup routes place the repository at ~/tutorial.

Check which Conda environment is active:

echo "${CONDA_PREFIX:-No Conda environment is active}"

The path should end in /tutorial-env. If it does not, activate the tutorial environment using the command for your setup:

Live tutorial

source /opt/tutorial/activate.sh

Self-managed

conda activate tutorial-env

Continue with either setup

1. Enter the quickstart directory

cd ~/tutorial/examples/taskvine/quickstart
ls

You should see at least:

README.md  taskvine-quickstart.py

After a previous run, you may also see generated directories such as vine-run-info. This is normal.

2. Start the manager

In your current terminal, run:

python taskvine-quickstart.py

The program prints a manager name containing your username, selects an available port, submits five tasks, and waits:

Manager name: taskvine-quickstart-<USERNAME>
Listening on port: <PORT>

In a second terminal, run:
vine_worker ... localhost <PORT>

Submitting tasks...
Waiting for a worker to connect and complete the tasks...

Nothing is wrong when the program waits here. The manager has work to perform but does not yet have a worker.

Leave this terminal running.

3. Open a second terminal

Live tutorial

Open another terminal on your computer and connect to the same tutorial server. Replace the highlighted placeholders with the username and server printed on your credential card:

ssh <USERNAME>@<SERVER>

After logging in, activate the shared tutorial tools:

source /opt/tutorial/activate.sh

Self-managed

Open another terminal on the same Linux system and activate the tutorial environment:

conda activate tutorial-env

Continue with either setup

4. Start the worker directly

Return briefly to the manager terminal and copy the complete vine_worker command it printed. Run that command in the second terminal.

It will look similar to:

vine_worker localhost <PORT>

Use the actual port printed by your manager instead of <PORT>. Live participants should run this command on the tutorial server, not on their laptop.

The worker connects directly to the manager and begins requesting tasks. This is the only primary tutorial example that starts a worker directly; later exercises use vine_factory to discover a named manager and maintain workers for it.

5. Confirm success

Return to the manager terminal. The five tasks may finish in a different order from the order in which they were submitted.

You should finish with:

Quickstart complete: 5 of 5 tasks succeeded.

The manager declared one remote file, attached it to five tasks, and captured the standard output from each Linux command.

6. Connect the code to the execution model

The essential task definition is:

task = vine.Task(f"grep -i {keyword} warandpeace.txt | wc")
task.add_input(shared_text, "warandpeace.txt")
task.set_cores(1)
manager.submit(task)

vine.Task receives a command line. When a worker runs this task, TaskVine creates a private sandbox, makes the declared input available as warandpeace.txt, and executes the grep and wc pipeline there.

The command writes its result to standard output, so the manager retrieves it through:

completed.output

This model is useful for existing Linux commands, shell scripts, compiled programs, and other command-line applications.

Reset

The manager exits after all five tasks finish. Return to the worker terminal and press Ctrl-C to stop the worker.

If the exercise is interrupted, press Ctrl-C once in each terminal. Restart the manager and use the newly printed worker command because its port may change.

What you have learned

  • A TaskVine manager defines and coordinates work.
  • A worker supplies execution resources.
  • vine.Task describes a Unix command line.
  • Declared files are mapped into private task sandboxes.
  • Task results may complete in a different order from submission.

TaskVine hands-on navigation